Get Operation

Read an operation’s status and result. Optionally wait for it to finish.

GET /api/v1/operations/{operation_id}

cURL

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

Running

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "question",
  "status": "running",
  "progress": null,
  "resource": { "type": "question", "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.

Returns the operation at once, or, with wait, holds the request until the operation finishes or wait seconds pass, whichever comes first. A long-poll with wait=20 replaces about ten short polls and never runs past the 29-second request limit.

Every endpoint that starts long-running work returns an operation. Its type says what the work is:

type	Started by	resource	result on success	Read scope	Write scope	Cancellable
question	Create Question	question	question_id, session_id, status, answer, reason, attachments	sessions:read	sessions:write	No
review	Create Review	review	review_id, findings (counts), redline_file_id	reviews:read	reviews:write	Yes
review_redline	Generate Redline	review	file_id	reviews:read	reviews:write	Before it starts
document_action	Document actions	file	action, file_ids, summary	files:read	files:write	Yes
draft	Create Draft	session	file_id, values, url	files:read	files:write	Yes
report_run	Run Report	report	cells_completed, cells_total	reports:read	reports:write	Yes
report_export	Export Report	report	file_id	reports:read	reports:write	No
repository_indexing	Add Documents	repository	indexed, failed	repositories:read	repositories:write	No
playbook_generation	Generate Playbook	playbook	playbook_id	playbooks:read	playbooks:write	No

Authentication

Send an API key, or an OAuth access token, as a bearer token in the Authorization header. A token needs the read scope of the operation’s type, from the table above, such as sessions:read for a question. Without it the call returns 403 with "error": "insufficient_scope" and a WWW-Authenticate header naming the scope.

Path parameters

operation_id · string · required

The operation id returned when the work was started.

Query parameters

wait · integer · default: "0"

Seconds to wait for the operation to finish, from 0 to 20. The response comes back as soon as it finishes. When your organisation already has many requests waiting, the response comes back at once; ask again after poll_after_seconds.

Response

Returns 200 with the operation, whether or not it has finished. queued and running mean ask again after poll_after_seconds. When status is succeeded, result holds the fields the table above lists for the operation’s type. For a question, that is its question_id, session_id, status, answer, reason and attachments (file ids).

resource.id is null until the work has created its resource, such as the session a draft runs in. Numbers in result and progress are JSON numbers. A finished operation keeps its last progress.

cURL

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

Running

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "question",
  "status": "running",
  "progress": null,
  "resource": { "type": "question", "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
400	invalid_wait	wait is outside 0–20.
400	bad_request	wait is not a whole number.
403	insufficient_scope	The OAuth token lacks the operation type’s read scope.
404	resource_not_found	No operation with this id that you started.