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

# Generate Redline

> Turn some of a review's proposed amendments into tracked changes.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Writes the amendments of the findings you choose into the reviewed documents as tracked changes. The output is a new file: a DOCX when the amendments change one document, or a ZIP of one DOCX per document when they change several. By default it includes every issue that has a proposed amendment. Pass `finding_ids` to choose a subset.

A finished review already has a redline of every proposed amendment in its `redline_file_id`. Use this endpoint when you want only some of them. The new file does not replace the review's `redline_file_id`: read its id from the operation's `result`. It lives with the review, so anyone who can read the review can read it.

It runs as an operation, because a large document can take a few minutes. It works on `playbook` and `instructions` reviews whose reviewed documents include a DOCX.

## Authentication

Requires an API key, or an OAuth token with `reviews:write`. Reading the new file needs `files:read`.

## Path parameters

**review\_id** `string` *required*

The review id. The review must be `completed`.

## Headers

**Idempotency-Key** `string`

A unique key for this request, such as a UUID. A repeat with the same key and body within 30 days returns the same operation and makes no second file.

## Body parameters

The body is optional: an empty body takes every default.

**finding\_ids** `string[]`

The findings whose amendments to apply, from [List Findings](/api-reference/reviews/list-findings). Each must belong to this review and propose an amendment. Defaults to every finding whose `status` is `issue` and that proposes an amendment.

**wait** `integer` (default: 0)

Seconds to wait for the redline before responding, from `0` to `20`. A short document often finishes inside `20`.

**callback\_url** `string`

A public HTTPS URL that receives a signed `operation.succeeded`, `operation.failed` or `operation.cancelled` event when the redline is ready. API keys only.

## Response

Returns `202` with an [operation](/api-reference/operations/get-operation) of type `review_redline`. Its `resource` is the review. A repeat with the same `Idempotency-Key` returns `200` with the same operation.

When `status` is `succeeded`, `result` is `{ "file_id" }`: the new tracked-changes DOCX, or a ZIP of DOCX files when the amendments changed more than one document. Read its `content_type` with [Get File](/api-reference/files/get-file) before you open it. Running this endpoint again makes a new file. When none of the chosen amendments could be applied, the operation fails with `error.code` `no_amendments`. When the redline could not be written, it fails with `redline_failed`, which is `retryable`. Cancelling the operation stops it: a file made before the cancel arrived is deleted, and the operation ends `cancelled`.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reviews/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58/redline" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c3e7a10-4f2b-4d58-a6e1-0b8d2c5f7a93" \
  -d '{
    "finding_ids": [
      "71911999-dbe8-438b-8f03-dfd349c2da40",
      "fcba2f4f-f1af-4680-8821-5e75541824f3"
    ],
    "wait": 20
  }'
```

```json Running theme={null}
{
  "id": "34816160-6e61-42e0-a43e-3a15684042ad",
  "type": "review_redline",
  "status": "running",
  "progress": null,
  "resource": { "type": "review", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T09:10:00Z",
  "updated_at": "2026-10-13T09:10:06Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "34816160-6e61-42e0-a43e-3a15684042ad",
  "type": "review_redline",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "review", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": { "file_id": "940a76a4-7c58-48df-92a5-9c726be73c26" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T09:10:00Z",
  "updated_at": "2026-10-13T09:10:14Z",
  "completed_at": "2026-10-13T09:10:14Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | A `finding_ids` entry does not belong to this review or proposes no amendment, or no finding proposes one. |
| 400 | `unsupported_file_type` | The review has no DOCX to mark up. |
| 400 | `invalid_request_body` | The body is not valid JSON, has an unknown field, or `finding_ids` is empty. |
| 404 | `resource_not_found` | No review with this id, or the caller cannot read it. |
| 409 | `session_still_processing` | The review is still queued or running. |
| 409 | `resource_conflict` | The review failed or was cancelled, or it is a `counterparty_edits` review. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |


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