Generate Playbook

curl -X POST "https://api.wordsmith.ai/api/v1/playbooks/generate" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f6b1c9e-generate-supply-playbook" \
  -d '{
    "name": "Supply agreement – buyer side",
    "file_ids": [
      "784df158-f644-4d78-8ad4-f4e2de319c98",
      "4e1f50a9-c1f1-4b8d-8b3a-96d7aa651e23"
    ]
  }'

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "running",
  "progress": { "stage": "drafting_checks", "completed": 6, "total": null },
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:42Z",
  "completed_at": null
}

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": { "playbook_id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:05:31Z",
  "completed_at": "2026-10-13T11:05:31Z"
}

POST

api

playbooks

generate

curl -X POST "https://api.wordsmith.ai/api/v1/playbooks/generate" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f6b1c9e-generate-supply-playbook" \
  -d '{
    "name": "Supply agreement – buyer side",
    "file_ids": [
      "784df158-f644-4d78-8ad4-f4e2de319c98",
      "4e1f50a9-c1f1-4b8d-8b3a-96d7aa651e23"
    ]
  }'

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "running",
  "progress": { "stage": "drafting_checks", "completed": 6, "total": null },
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:42Z",
  "completed_at": null
}

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": { "playbook_id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:05:31Z",
  "completed_at": "2026-10-13T11:05:31Z"
}

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

Starts building a playbook with AI, as the Wordsmith app’s playbook import does. Wordsmith reads your precedent contracts and drafts the checks, each with its instructions and standard position. Generation usually takes several minutes, so the call returns an operation straight away. See Long-running operations for how to wait for it. The operation’s resource names the new playbook. It has no checks until the operation succeeds; checks appear one by one while it runs, and progress.completed counts them. If the operation fails, Wordsmith deletes the playbook when it still has no checks. A generation cannot be cancelled. On success, result holds { "playbook_id" }. Read the checks with Get Playbook and adjust them with Update Check. Like any new playbook, it is visible only to you until you share it with Update Sharing.

Authentication

Requires an API key, or an OAuth token with playbooks:write and files:read.

Headers

string

A unique key for this request. A retry with the same key and body within 30 days returns the same operation instead of starting a second one. See Retrying safely.

Body parameters

string

required

The name of the new playbook, up to 200 characters.

string[]

required

1 to 10 example or precedent contracts, as file_ids from the files API. Signed agreements on your own terms work best: Wordsmith takes their positions as your standard. A file_id comes from Complete Upload or Import File, not from Upload URL, which returns a job_id.

integer

default:"0"

Seconds to wait for the operation to finish before responding, from 0 to 20. Generation rarely finishes this fast, so expect a running operation.

string

An HTTPS URL that receives a signed POST with the operation when it finishes. API keys only. See Callbacks.

Response

Returns 202 with the operation, of type playbook_generation. A repeat with the same Idempotency-Key returns 200 with the same operation.

curl -X POST "https://api.wordsmith.ai/api/v1/playbooks/generate" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f6b1c9e-generate-supply-playbook" \
  -d '{
    "name": "Supply agreement – buyer side",
    "file_ids": [
      "784df158-f644-4d78-8ad4-f4e2de319c98",
      "4e1f50a9-c1f1-4b8d-8b3a-96d7aa651e23"
    ]
  }'

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "running",
  "progress": { "stage": "drafting_checks", "completed": 6, "total": null },
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:42Z",
  "completed_at": null
}

{
  "id": "4e1e3084-d717-4cdb-aaaa-e67316c599d3",
  "type": "playbook_generation",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "playbook", "id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "result": { "playbook_id": "54ace248-3356-480d-8568-91a3be5b49bc" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:05:31Z",
  "completed_at": "2026-10-13T11:05:31Z"
}

Errors

Status	`error_code`	When
400	`invalid_request_body`	`name` is missing, `file_ids` is empty or has more than 10 ids.
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 create playbooks.
403	`insufficient_scope`	An OAuth token without `files:read`.
404	`resource_not_found`	A `file_id` does not exist, or the caller cannot read it.
409	`scan_in_progress`	A file has not finished malware scanning. Retry in a few seconds.
409	`idempotency_key_reused`	The `Idempotency-Key` was used in the last 30 days with a different body.

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

Headers

Body parameters

Response

Errors

​Authentication

​Headers

​Body parameters

​Response

​Errors

Authentication

Headers

Body parameters

Response

Errors