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

# Review status lifecycle

> The states a review on a source request moves through

Every review on a source request reports a `status` that moves through a fixed state machine. A review starts in `DRAFT` when the reviewer creates it and ends at one of three terminal states when they submit.

Use the [submit review](/cookbooks/reviews#submit-the-review) endpoint to leave `DRAFT`. Any transition that is not allowed returns `409 Conflict`. Status changes are recorded with timestamps (`changes_requested_at`, `approved_at`, `rejected_at`).

The parent request has its own lifecycle — see [Request status lifecycle](/request-status).

## State diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> DRAFT
    DRAFT --> CHANGES_REQUESTED: request_changes
    DRAFT --> APPROVED: approve
    DRAFT --> REJECTED: reject
```

## States

| Status              | Meaning                                                                           |
| ------------------- | --------------------------------------------------------------------------------- |
| `DRAFT`             | Private work-in-progress for the reviewer. Only that reviewer can see or edit it. |
| `CHANGES_REQUESTED` | The reviewer submitted a request for changes. Terminal for the review.            |
| `APPROVED`          | The reviewer approved. Terminal for the review.                                   |
| `REJECTED`          | The reviewer rejected. Terminal for the review.                                   |

## Transitions

* Creating a review starts it in `DRAFT`. Calling create again while a draft exists for that reviewer resumes that draft instead of creating a duplicate.
* `PATCH` on a review is allowed only while it is in `DRAFT`.
* `submit` with `approve`, `request_changes`, or `reject` moves the review out of `DRAFT` and advances the parent request with the same event.
* Submitted reviews are immutable.

For the full API recipe, see [Review source changes](/cookbooks/reviews).