> ## 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.

# Create Draft

> Draft a document from instructions and context, optionally starting from a blueprint.

> [!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).

Drafts a new DOCX or PDF [file](/api-reference/files/get-file). What it does depends on what you send:

| You send | Wordsmith |
| - | - |
| `instructions`, no `blueprint_id` | An agent drafts the document from scratch, using your context. |
| `blueprint_id` and `values`, and no context | Fills the blueprint with your values. No AI drafts anything, so this takes seconds. |
| `blueprint_id` with context, and some or no `values` | Drafts the empty placeholders from your context, then fills the blueprint. Your `values` are kept as you sent them. |

A blueprint is a document with placeholders, such as your standard NDA. Find one with [List Blueprints](/api-reference/blueprints/list-blueprints) and read its placeholders with [Get Blueprint](/api-reference/blueprints/get-blueprint). The blueprint must be published.

Give context in any mix of four forms:

* `instructions`: what to draft, or how to fill the blueprint.
* `context`: free text, such as a deal summary or an email from the business.
* `file_ids`: source documents, such as a term sheet or the heads of terms.
* `session_id`: a past Wordsmith conversation about the deal.

Each draft runs in a new Wordsmith conversation, so you can open it in the app and keep working on it. Drafting can take a minute or more, so the call returns an [operation](/proposed/objects#operation). Its `resource` is that conversation, `{ "type": "session" }`. Its `id` is `null` until the draft has started. A draft cancelled before it starts opens no conversation. A blueprint filled from your own values usually comes back `succeeded` within a `wait` of a few seconds. See [Long-running operations](/proposed/long-running-operations) for how to wait for the rest.

On success, `result` holds:

* `file_id`: the new document, in your own files. Read it with [Get File Download](/api-reference/files/get-file-download).
* `values`: for a blueprint, every placeholder value used, keyed by placeholder `key`. A value nothing was found for is `null` and left blank. To correct one, send the edited `values` back with the same `blueprint_id` and no context; no AI runs the second time. `null` for a draft without a blueprint.
* `url`: opens the conversation in Wordsmith, where the user can keep working on the draft.

The operation fails with `error.code`:

* `missing_values`: a required placeholder still has no value. The message names it; send it in `values`.
* `no_document`: the agent answered without drafting a document. Try clearer `instructions`.
* `draft_failed`: anything else went wrong, or the draft stopped without finishing. Retrying is safe.
* An API error code, such as `resource_not_found`: the blueprint, a file or the session became unreadable while the draft ran. The message says what; retrying the same request will not help.

## Authentication

Requires an API key, or an OAuth token with `files:write` and `files:read`: you need `files:read` to poll the operation and download the draft. Add `blueprints:read` to pass `blueprint_id` and `sessions:read` to pass `session_id`.

## 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 drafting twice. See [Retrying safely](/proposed/long-running-operations#retrying-safely-with-idempotency-key).

## Body parameters

**instructions** `string`

What to draft, up to 10,000 characters. For example: "A two-page side letter extending the exclusivity period to 31 March." Required without `blueprint_id`. With a blueprint, it steers how AI drafts the empty placeholders.

**blueprint\_id** `string`

The blueprint to draft from.

**values** `object`

Blueprint placeholder values you already know, keyed by placeholder `key`. AI never overrides them. Each value must fit its placeholder's `type`: a string (or number) for `text`, one of the `options` for `choice`, a list of `options` for `multi_choice`, `true` or `false` for `boolean`, and rows of strings for `table`. Only with `blueprint_id`.

**context** `string`

Free-text context, up to 20,000 characters.

**file\_ids** `string[]`

Up to 10 source documents, as `file_id`s from the [files API](/api-reference/files/upload-url). 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`.

**session\_id** `string`

A past conversation to use as context, from [List Sessions](/api-reference/sessions/list-sessions).

**output\_format** `string` (default: docx)

`docx` or `pdf`.

**file\_name** `string`

The name of the new file, without an extension, up to 255 characters. Defaults to the blueprint's or the draft's name, plus the date.

**wait** `integer` (default: 0)

Seconds to wait for the operation to finish before responding, from `0` to `20`.

**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 `draft`. A repeat with the same `Idempotency-Key` returns `200` with the same operation.

```bash From a blueprint theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/drafts" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d8f0b62-draft-nda-northwind" \
  -d '{
    "blueprint_id": "cb3b96b2-fb48-47c4-bd41-e484a8eb2f0f",
    "context": "We are exploring a warehousing partnership with Northwind. Talks start on 1 November.",
    "file_ids": ["e3b226fa-2b1e-48d4-9ae1-1bb3549f11a3"],
    "values": { "governing_law": "England and Wales" },
    "wait": 20
  }'
```

```bash From scratch theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/drafts" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c1e7a40-side-letter-exclusivity" \
  -d '{
    "instructions": "A short side letter extending the exclusivity period in the attached term sheet to 31 March 2027.",
    "file_ids": ["e3b226fa-2b1e-48d4-9ae1-1bb3549f11a3"],
    "wait": 20
  }'
```

```json Running theme={null}
{
  "id": "f4af05bf-e14d-46ee-9a25-a956282d8f3d",
  "type": "draft",
  "status": "running",
  "progress": { "stage": "drafting_values", "completed": 0, "total": 5 },
  "resource": { "type": "session", "id": "7a2c9e51-3f84-4b06-a1d7-5e9b0c2f8d63" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T12:10:00Z",
  "updated_at": "2026-10-13T12:10:20Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "f4af05bf-e14d-46ee-9a25-a956282d8f3d",
  "type": "draft",
  "status": "succeeded",
  "progress": { "stage": "rendering", "completed": 0, "total": 1 },
  "resource": { "type": "session", "id": "7a2c9e51-3f84-4b06-a1d7-5e9b0c2f8d63" },
  "result": {
    "file_id": "04d466ba-1dd7-455b-9c20-ea207b737f30",
    "values": {
      "counterparty_name": "Northwind Logistics Ltd",
      "effective_date": "1 November 2026",
      "term_years": "3",
      "governing_law": "England and Wales",
      "include_non_solicit": null
    },
    "url": "https://app.wordsmith.ai/chat/7a2c9e51-3f84-4b06-a1d7-5e9b0c2f8d63"
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T12:10:00Z",
  "updated_at": "2026-10-13T12:10:34Z",
  "completed_at": "2026-10-13T12:10:34Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | Neither `instructions` nor `blueprint_id` is set, `values` is sent without `blueprint_id`, a text field is over its limit, there are more than 10 `file_ids`, or the blueprint is not published. |
| 400 | `invalid_placeholder_values` | A key in `values` is not a placeholder of this blueprint, or a value does not fit its placeholder's `type`. `invalid_keys` lists them. |
| 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 | `insufficient_scope` | The token lacks `files:read`, or `blueprint_id` or `session_id` was sent without its scope. |
| 404 | `resource_not_found` | The blueprint, a file or the session 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. |
| 429 | `rate_limit_exceeded` | Too many new sessions. Retry after the `Retry-After` header. |


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