Get Operation

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"

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

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "question",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "question", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": {
    "question_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "session_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "status": "completed",
    "answer": "Liability is capped at GBP 50,000, and English law governs.",
    "reason": null,
    "attachments": []
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:41Z",
  "completed_at": "2026-10-14T09:00:41Z"
}

GET

api

operations

{operation_id}

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"

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

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "question",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "question", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": {
    "question_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "session_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "status": "completed",
    "answer": "Liability is capped at GBP 50,000, and English law governs.",
    "reason": null,
    "attachments": []
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:41Z",
  "completed_at": "2026-10-14T09:00:41Z"
}

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

string

required

The operation id returned when the work was started.

Query parameters

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

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

{
  "id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
  "type": "question",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "question", "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58" },
  "result": {
    "question_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "session_id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
    "status": "completed",
    "answer": "Liability is capped at GBP 50,000, and English law governs.",
    "reason": null,
    "attachments": []
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-14T09:00:00Z",
  "updated_at": "2026-10-14T09:00:41Z",
  "completed_at": "2026-10-14T09:00:41Z"
}

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.

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Path parameters

Query parameters

Response

Errors

​Authentication

​Path parameters

​Query parameters

​Response

​Errors

Authentication

Path parameters

Query parameters

Response

Errors