Generate Playbook

Build a playbook from precedent contracts.

POST /api/v1/playbooks/generate

cURL

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"
    ]
  }'

Running

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

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

Idempotency-Key · 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

name · string · required

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

file_ids · 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.

wait · 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.

callback_url · 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

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"
    ]
  }'

Running

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

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.