Create Draft

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

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

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

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

POST

api

drafts

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

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

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

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

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

Drafts a new DOCX or PDF 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 and read its placeholders with 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. 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 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.
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

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.

Body parameters

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.

string

The blueprint to draft from.

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.

string

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

string[]

Up to 10 source documents, as file_ids from the files API. A file_id comes from Complete Upload or Import File, not from Upload URL, which returns a job_id.

string

A past conversation to use as context, from List Sessions.

string

default:"docx"

docx or pdf.

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.

integer

default:"0"

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

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

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

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

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

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

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