Redline File

Edit a document from plain-language instructions, as tracked changes.

POST /api/v1/files/{file_id}/redline

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/files/9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6/redline" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a7d3f1c9-6e2b-4b84-8c05-9f1e3a7d2b60" \
  -d '{
    "instructions": "Change the governing law and jurisdiction to England and Wales. Make the notice period for termination for convenience 90 days.",
    "author_name": "Jane Smith"
  }'

Running

{
  "id": "6b67c458-643a-4173-8ec3-66ea73d009b6",
  "type": "document_action",
  "status": "running",
  "progress": {
    "stage": "redline",
    "completed": 0,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:01Z",
  "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.

Makes the edits your instructions describe, as tracked changes in a new DOCX. The original file is not changed. Use it for one-off edits, such as “make the governing law English law”.

The input can be a DOCX, a DOC, a PDF, or a text, Markdown or HTML file. Anything but a DOCX is converted to DOCX first, so its layout may change.

The action runs as an operation of type document_action: the response comes back straight away, and the work runs in the background. Wait for it with wait, a callback_url, or Get Operation. The new files land in your private space. The input files are not changed. Document actions use no credits.

Authentication

Send an API key, or an OAuth access token with both the files:write and files:read scopes. files:write lets the action create its output; files:read lets it read the inputs. A token without either gets 403 with "error": "insufficient_scope".

Path parameters

file_id · string (uuid) · required

The file to edit.

Headers

Idempotency-Key · string

A unique key for this request, such as a UUID, up to 255 characters. A repeat with the same key within 30 days returns 200 with the same operation and does the work once. A repeat with a different body returns 409 idempotency_key_reused.

Body parameters

instructions · string · required

The edits to make, in plain language, up to 10,000 characters. Quote the text to change where you can.

author_name · string

The author shown on each tracked change in Word. Defaults to your redline author name, or your organisation’s name.

acting_party · string

The party you act for, such as "Buyer" or a party’s name. Edits lean towards this party. When omitted, Wordsmith infers it from the document and your company profile.

wait · integer · default: "0"

Seconds to wait for the action to finish before responding, from 0 to 20. Short documents with a few edits often finish inside 20.

callback_url · string

A public HTTPS URL that receives a signed operation.succeeded, operation.failed or operation.cancelled event when the action finishes. API keys only: an OAuth caller waits or polls instead.

Response

Returns 202 with an operation of type document_action. Its resource is the input file. A repeat with the same Idempotency-Key returns 200 with the same operation.

When status is succeeded, result is { "action": "redline", "file_ids", "summary" }. file_ids holds one id: the edited DOCX. summary is { "insertions", "deletions" }, counting the tracked changes in the output, or null if they could not be counted.

When status is failed, error.code says why:

error.code	When
no_changes_applied	None of the edits could be made, so no file was created. Quote the exact text to change and try again.
resource_not_found	An input was deleted, or your access to it removed, before the work ran.
invalid_document	An input could not be read: it is damaged, password-protected or not a valid DOCX or PDF. Retrying does not help.
action_failed	The action failed for another reason. error.retryable is true: try again.

id · string (uuid)

The operation’s id.

type · string

document_action.

status · string

queued until a worker starts the action, then running, succeeded, failed or cancelled.

progress · object | null

{ "stage", "completed", "total" }. null until the work starts.

resource · object

{ "type": "file", "id" }: the input file.

result · object | null

Set when status is succeeded.

error · object | null

{ "code", "message", "retryable" }, set when status is failed.

poll_after_seconds · integer | null

When to ask again. null once the operation has finished.

created_at · string

ISO 8601 UTC.

updated_at · string

ISO 8601 UTC.

completed_at · string | null

ISO 8601 UTC, once the operation has finished.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/files/9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6/redline" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a7d3f1c9-6e2b-4b84-8c05-9f1e3a7d2b60" \
  -d '{
    "instructions": "Change the governing law and jurisdiction to England and Wales. Make the notice period for termination for convenience 90 days.",
    "author_name": "Jane Smith"
  }'

Running

{
  "id": "6b67c458-643a-4173-8ec3-66ea73d009b6",
  "type": "document_action",
  "status": "running",
  "progress": {
    "stage": "redline",
    "completed": 0,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:01Z",
  "completed_at": null
}

Errors

Status	error_code	When
400	invalid_request_body	The body is not valid JSON, has an unknown field, or instructions is missing, empty or over 10,000 characters.
400	unsupported_file_type	The file is not a DOCX, DOC, PDF, text, Markdown or HTML file.
400	invalid_wait	wait is not from 0 to 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.
400	bad_request	callback_url was sent with an OAuth token.
403	insufficient_scope	The OAuth token lacks files:write or files:read.
403	forbidden	Your user may not upload files, so the output has nowhere to go.
404	resource_not_found	The file does not exist, or you cannot read it.
409	scan_in_progress	The file’s malware scan has not finished. Retry in a few seconds.
409	idempotency_key_reused	The Idempotency-Key was used within 30 days with a different request.