> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrospectives API

> Read and update retrospective state programmatically: the two status vocabularies, incident retrospective steps, and where to find each endpoint.

## Overview

Retrospective state is readable and writable through the API — useful for a completion dashboard of your own, a nudge bot, or a script that skips a step that does not apply to a class of incident.

Full request and response schemas for every endpoint are in the **API Reference** tab. This page covers what the reference cannot: which status vocabulary applies where, and which of them means what.

***

## Three Status Vocabularies

The most common mistake with this API is treating retrospective status as one thing. It is three, at three different levels, and they overlap without matching.

### Incident-level: `retrospective_progress_status`

On the incident, describing the retrospective as a whole:

| Value         | Meaning                                         |
| ------------- | ----------------------------------------------- |
| `not_started` | No step has been begun                          |
| `active`      | The retrospective is in progress                |
| `completed`   | Every required step is done                     |
| `skipped`     | The retrospective was skipped for this incident |

Also available in Liquid as `{{ incident.retrospective_progress_status }}` — see [Incident Variables](/liquid/incident-variables).

### Step-level: `status`

On each incident retrospective step, describing one step:

| Value         | Meaning         |
| ------------- | --------------- |
| `todo`        | Not begun       |
| `in_progress` | Being worked on |
| `completed`   | Done            |
| `skipped`     | Skipped         |

### Document-level: `status`

On the retrospective document itself — the write-up, not its progress:

| Value       | Meaning       |
| ----------- | ------------- |
| `draft`     | Being written |
| `published` | Shared        |

This is the status [retrospective workflows](/workflows/retrospective-workflows) trigger on. When a retrospective workflow says "Status Updated", it means *this* status, not the incident's progress.

### The Overlap Problem

<Warning>
  No two of these three sets are the same, and none of them share a complete vocabulary.

  |                   | Values                                          |
  | ----------------- | ----------------------------------------------- |
  | Incident progress | `not_started`, `active`, `completed`, `skipped` |
  | Step              | `todo`, `in_progress`, `completed`, `skipped`   |
  | Document          | `draft`, `published`                            |

  `completed` and `skipped` appear in two of the three. Nothing appears in all three.

  A filter written against `not_started` finds no steps, one written against `todo` finds no incidents, and one written against `published` finds neither — in every case silently, returning an empty result rather than an error.
</Warning>

Before you write a query, decide which of the three questions you are asking: *how far along is the retrospective* (incident), *is this particular step done* (step), or *has the write-up been shared* (document).

***

## Reading Retrospective State

The incident's own `retrospective_progress_status` attribute gives the summary. Fetch the incident and read it — no separate call is required for the headline state.

For step detail, `GET /v1/incident_retrospective_steps/{id}` returns one step:

| Field                   | Meaning                                          |
| ----------------------- | ------------------------------------------------ |
| `title`                 | The step name                                    |
| `description`           | The step's instructions                          |
| `status`                | `todo`, `in_progress`, `completed`, or `skipped` |
| `kind`                  | The type of step                                 |
| `due_date`              | When the step is due                             |
| `position`              | Order within the retrospective                   |
| `skippable`             | Whether this step is allowed to be skipped       |
| `incident_id`           | The incident it belongs to                       |
| `retrospective_step_id` | The process step it was created from             |

`skippable` records whether the process marked this step required, and the API treats it as information rather than as a constraint — a `PUT` setting `status` to `skipped` succeeds either way. Rootly's own UI offers the skip action only where `skippable` is `true`, so a script that ignores the flag can leave a retrospective in a state the UI would not have allowed. Read it and honor it.

***

## Finding a Step ID

There is no endpoint that lists an incident's retrospective steps directly. They hang off the retrospective, so fetch that and ask for the steps:

```bash theme={null}
curl --request GET \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url 'https://api.rootly.com/v1/post_mortems/RETROSPECTIVE_ID?include=incident_retrospective_steps'
```

The `included` array carries one entry per step, and its `id` is the `STEP_ID` used below. To get the `RETROSPECTIVE_ID` in the first place, list retrospectives with `GET /v1/post_mortems` or read one from its incident.

<Note>
  The resource is named `post_mortems` in the API even where the product says *retrospective*. The two mean the same thing — see the status vocabularies above.
</Note>

***

## Updating a Step

`PUT /v1/incident_retrospective_steps/{id}` updates one step. This is how a script marks a step done or skips one that does not apply.

```bash theme={null}
curl --request PUT \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/incident_retrospective_steps/STEP_ID \
--data '{
  "data": {
    "type": "incident_retrospective_steps",
    "attributes": {
      "status": "completed"
    }
  }
}'
```

<Note>
  Steps are the unit of change. There is no endpoint that sets the incident's `retrospective_progress_status` directly — it follows from the state of the steps beneath it. Drive the steps and the incident-level status keeps itself current.
</Note>

***

## Configuring the Process

Everything above is about one incident's retrospective. The *shape* every retrospective takes — which steps exist, in what order, with what defaults — is configured separately, and also has API endpoints:

* **Retrospective processes** — `/v1/retrospective_processes`, plus its groups and steps
* **Process steps** — `/v1/retrospective_steps/{id}`
* **Retrospective configurations** — `/v1/retrospective_configurations`

Changing a process affects retrospectives created afterwards. See [Configuring Retrospective Processes](/retrospectives/configuring-retrospective-processes) for what these control.

***

## Exporting

Exporting a finished retrospective — to PDF, Confluence, and the other destinations — is a separate capability, covered in [Exporting Retrospectives](/collaborative-retrospectives/exporting-retrospectives).

***

## Related Pages

<CardGroup cols={2}>
  <Card title="Configuring Processes" icon="sliders" href="/retrospectives/configuring-retrospective-processes">
    The steps and structure every retrospective inherits.
  </Card>

  <Card title="Exporting Retrospectives" icon="file-export" href="/collaborative-retrospectives/exporting-retrospectives">
    Getting a finished retrospective out of Rootly.
  </Card>
</CardGroup>