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

> Propose source additions or removals and collect reviews before they take effect

Requests let workspace members propose source additions or removals and collect reviews before the change takes effect. You create a request in `DRAFT`, attach the proposed changes, submit it for review, then reviewers approve, request changes, or reject.

## Prerequisites

* An AiQL API key in the `AIQL_API_KEY` environment variable
* A workspace ID (see [Quickstart](/quickstart) to create one)
* At least one source (document) ID in that workspace to target with a change

## Create a request

Create a request with a title. It starts in `DRAFT` so you can still edit it and add changes.

```bash theme={null}
curl -X POST https://api.aiql.io/requests \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add Q1 report",
    "description": "Propose adding the Q1 financial report",
    "labels": ["finance"],
    "assignee_ids": ["REVIEWER_USER_ID"]
  }'
```

The response includes an `id` and `status` of `DRAFT`. Save the request ID for the steps below.

## Add changes

While the request is in `DRAFT`, attach the sources you want to add or remove. `type` is either `SOURCE_ADD` or `SOURCE_REMOVE`.

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/changes \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SOURCE_ADD",
    "description": "Q1 financial report PDF",
    "source_id": "YOUR_SOURCE_ID"
  }'
```

Remove a change the same way while still in `DRAFT`:

```bash theme={null}
curl -X DELETE https://api.aiql.io/requests/YOUR_REQUEST_ID/changes/YOUR_CHANGE_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
```

Content edits (`title`, `description`, `labels`, `assignees`) and change add/remove are only allowed while the request is in `DRAFT`. Editing after submit returns `409 Conflict`.

## Submit for review

When the request is ready, the author transitions it to `OPEN`. Only the author can call this.

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/transition \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"event": "submit"}'
```

The request moves to `OPEN` and sets `opened_at`. See [Request status lifecycle](/request-status) for every allowed transition.

## Start a review

A reviewer creates (or resumes) a draft review on an open request. Calling create again while a draft already exists for that reviewer resumes the draft instead of creating a duplicate.

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/reviews \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"description": "Looks good overall; checking figures"}'
```

Draft reviews are private to the reviewer. Other members only see a review after it is submitted.

## Comment on a review

Add a comment while working through the review:

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/reviews/YOUR_REVIEW_ID/comments \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"content": "Please confirm the source date range covers Q1."}'
```

## Submit the review

Submit with `approve`, `request_changes`, or `reject`. This moves the review out of `DRAFT` and advances the parent request with the same event.

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/reviews/YOUR_REVIEW_ID/submit \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"event": "approve"}'
```

Submitted reviews are immutable. See [Review status lifecycle](/review-status) for the review state machine.

Any transition that is not allowed returns `409 Conflict`.

## Reopen after feedback

If a reviewer requested changes or rejected the request, the author can reopen it:

```bash theme={null}
curl -X POST https://api.aiql.io/requests/YOUR_REQUEST_ID/transition \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"event": "reopen"}'
```

`reopen` moves `CHANGES_REQUESTED` or `REJECTED` back to `OPEN` and refreshes `opened_at`.

## List requests

List every request in the workspace, or only the ones you authored or are assigned to.

```bash theme={null}
curl https://api.aiql.io/requests \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"

curl "https://api.aiql.io/requests/mine?role=assignee" \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
```

`role` accepts `any` (default), `author`, or `assignee`. Results are returned a page at a time — see [Pagination](/pagination).

## Get a request with reviews

```bash theme={null}
curl https://api.aiql.io/requests/YOUR_REQUEST_ID \
  -H "Authorization: Bearer $AIQL_API_KEY" \
  -H "AiQL-Workspace: YOUR_WORKSPACE_ID"
```

The detail response includes `changes` and visible `reviews` (other reviewers' drafts are hidden).

<Tip>
  Assign reviewers with `assignee_ids` when you create or update a draft request so they can find it under `/requests/mine?role=assignee`.
</Tip>