Skip to main content
POST
Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.
Starts a review and returns an 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.
  • 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 and finish with Complete Upload, or use 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 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

​
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

​
string
required
The review flow: playbook or instructions.
​
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.
​
string
The playbook to run. Required when type is playbook, and refused otherwise.
​
string
What to check, in plain language, up to 10,000 characters. Required when type is instructions, and refused otherwise.
​
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.
​
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.
​
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. 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. 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

​
Errors