Generate Redline

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

POST /api/v1/reviews/{review_id}/redline

cURL

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
  }'

Running

{
  "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
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

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

cURL

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
  }'

Running

{
  "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
}

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.