> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.