> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Playbook

> Build a playbook from precedent contracts.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Starts building a [playbook](/proposed/objects#playbook-and-check) 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](/proposed/objects#operation) straight away. See [Long-running operations](/proposed/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](/api-reference/playbooks/get-playbook) and adjust them with [Update Check](/api-reference/playbooks/update-check). Like any new playbook, it is visible only to you until you share it with [Update Sharing](/api-reference/sharing/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](/proposed/long-running-operations#retrying-safely-with-idempotency-key).

## 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_id`s from the [files API](/api-reference/files/upload-url). Signed agreements on your own terms work best: Wordsmith takes their positions as your standard. A `file_id` comes from [Complete Upload](/api-reference/files/complete-upload) or [Import File](/api-reference/files/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](/proposed/callbacks).

## Response

Returns `202` with the [operation](/proposed/objects#operation), of type `playbook_generation`. A repeat with the same `Idempotency-Key` returns `200` with the same operation.

```bash cURL theme={null}
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"
    ]
  }'
```

```json Running theme={null}
{
  "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
}
```

```json Succeeded theme={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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.