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

# Create Review

> Start a playbook or instructions review of one or more files.

> [!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).

Starts a review and returns an [operation](/api-reference/operations/get-operation) that tracks it. A review takes minutes, so the response comes back before it finishes. Poll the operation, long-poll it with `wait`, or receive a callback.

`type` picks one of two review flows:

* **`playbook`** runs the checks of a saved playbook against the files. Find playbook ids with [List Playbooks](/api-reference/playbooks/list-playbooks).
* **`instructions`** builds checks from your free-text `instructions`, then runs them. Use it when no playbook fits.

Every input is a `file_id` from the files API. To get one, upload the bytes with [Upload URL](/api-reference/files/upload-url) and finish with [Complete Upload](/api-reference/files/complete-upload), or use [Import File](/api-reference/files/import-file) for a URL. The review works on its own copies of the files, so your files stay where they are.

When the checks propose amendments and the first file is a DOCX, the review also writes a tracked-changes redline of them. Its id is the review's `redline_file_id`. To redline only some findings, use [Generate Redline](/api-reference/reviews/generate-redline) once the review has finished.

## Authentication

Requires an API key, or an OAuth token with `reviews:write` and `files:read`. The caller's role must be allowed to start document reviews and to upload files.

## 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 starts no new review. A repeat with a different body returns `409 idempotency_key_reused`.

## Body parameters

**type** `string` *required*

The review flow: `playbook` or `instructions`.

**file\_ids** `string[]` *required*

The files to review, 1 to 10, each a DOCX or PDF, as the ids this API returns. Files are reviewed together, such as an agreement and its schedules. A file may appear once.

**playbook\_id** `string`

The playbook to run. Required when `type` is `playbook`, and refused otherwise.

**instructions** `string`

What to check, in plain language, up to 10,000 characters. Required when `type` is `instructions`, and refused otherwise.

**party** `string`

The side the review acts for, as named in the document, e.g. `"Customer"`. Up to 200 characters. When omitted, the review runs without one and the review's `party` stays `null`.

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

Seconds to wait for the review to finish before responding, from `0` to `20`. Most reviews take longer, so the operation usually comes back `queued` or `running`.

**callback\_url** `string`

A public HTTPS URL that receives a signed `operation.succeeded`, `operation.failed` or `operation.cancelled` event when the review finishes. API keys only: an OAuth caller long-polls instead.

## Response

Returns `202` with an operation of type `review`. Its `resource` is the new review, which you can read at once with [Get Review](/api-reference/reviews/get-review). A repeat with the same `Idempotency-Key` returns `200` with the same operation.

While the review runs, `progress.stage` is `checks`, then `redline`, and `progress.completed` counts the checks with a result out of `progress.total`.

When `status` is `succeeded`, `result` holds `review_id`, the finding counts and `redline_file_id`. Read the findings with [List Findings](/api-reference/reviews/list-findings). A review that stops is `failed` with `error.code` `review_failed`, or `worker_lost` when its worker stopped responding. Both are `retryable`. Cancelling the operation stops the review.

## Examples

```bash Playbook theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reviews" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d1f4c2a-9b3e-4a68-8e05-c2f1d9a7b634" \
  -d '{
    "type": "playbook",
    "file_ids": ["9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"],
    "playbook_id": "2c4b8f90-5d1e-4a37-b6e2-c8f0a3d71e45",
    "party": "Customer"
  }'
```

```bash Instructions theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reviews" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4e2b9d71-0c6a-4f13-b8e7-5a9c3d1f0e82" \
  -d '{
    "type": "instructions",
    "file_ids": ["9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"],
    "instructions": "Check that liability is capped at 12 months of fees, that either party can terminate for convenience on 90 days notice, and that English law governs."
  }'
```

```bash Playbook theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reviews" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d1f4c2a-9b3e-4a68-8e05-c2f1d9a7b634" \
  -d '{
    "type": "playbook",
    "file_ids": ["9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"],
    "playbook_id": "2c4b8f90-5d1e-4a37-b6e2-c8f0a3d71e45",
    "party": "Customer"
  }'
```

```json Queued theme={null}
{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "review",
  "status": "queued",
  "progress": null,
  "resource": { "type": "review", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T09:00:00Z",
  "updated_at": "2026-10-13T09:00:01Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "review",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "review", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": {
    "review_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "findings": { "total": 32, "issues": 7, "high": 2, "medium": 3, "low": 2 },
    "redline_file_id": "c71e2a90-4b3d-4f68-9e15-8d0a6b2f3c47"
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T09:00:00Z",
  "updated_at": "2026-10-13T09:03:41Z",
  "completed_at": "2026-10-13T09:03:41Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | A required field is missing, `file_ids` is empty, has more than 10 entries or names a file twice, or a field is set that does not belong to `type`. |
| 400 | `unsupported_file_type` | A file is not a DOCX or PDF. |
| 400 | `invalid_wait` | `wait` is outside `0`–`20`. |
| 400 | `invalid_callback_url` | `callback_url` is not a public HTTPS URL. |
| 400 | `callback_signing_unavailable` | The API key has no webhook secret to sign the callback with. Create a new API key, or long-poll the operation instead. |
| 403 | `forbidden` | The caller's role cannot start document reviews or upload files. |
| 403 | `insufficient_scope` | The OAuth token lacks `reviews:write` or `files:read`. |
| 404 | `resource_not_found` | A file or the playbook does not exist, or the caller cannot read it. |
| 409 | `scan_in_progress` | A file has not finished its malware scan. Retry in a few seconds. |
| 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.