Cancel Operation

Ask a queued or running operation to stop.

POST /api/v1/operations/{operation_id}/cancel

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/operations/3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90/cancel" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "report_run",
  "status": "running",
  "progress": null,
  "resource": { "type": "report", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:01Z",
  "completed_at": null
}

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

Asks the work behind an operation to stop, and returns the operation. Cancellation is best-effort: a running operation stops at its next safe point, so the response can still read running for a few seconds before status becomes cancelled.

Reviews, redlines, document actions, drafts and report runs can be cancelled. Stopping a review needs edit access to it, as the web app’s Stop does. Work already done is kept, such as computed report cells.

A question, a report export, repository indexing and playbook generation cannot be cancelled. Once started they run to the end, so cancelling one returns 409 operation_not_cancellable; the work finishes on its own. Get Operation lists every type.

Authentication

Send an API key, or an OAuth access token, as a bearer token in the Authorization header. A token needs the write scope of the operation’s type, such as reviews:write for a review or reports:write for a report run. A write scope also grants its read scope, except files:write: a document action or a draft needs files:read and files:write. Without them the call returns 403 with "error": "insufficient_scope", naming every scope the token lacks.

Path parameters

operation_id · string · required

The operation to cancel.

Response

Returns 200 with the operation. Its status is running while the work stops, then cancelled.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/operations/3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90/cancel" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "report_run",
  "status": "running",
  "progress": null,
  "resource": { "type": "report", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:01Z",
  "completed_at": null
}

Errors

Status	error_code	When
403	insufficient_scope	The OAuth token lacks the operation type’s write scope, or its read scope where the write scope does not grant it.
403	forbidden	The caller cannot edit the review the operation runs.
404	resource_not_found	No operation with this id that you started.
409	operation_finished	The operation is already succeeded, failed or cancelled.
409	operation_not_cancellable	The operation’s work runs to the end once started, as a question or an export does.