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

# Redline File

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

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

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](/api-reference/operations/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.

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

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

```json Succeeded theme={null}
{
  "id": "6b67c458-643a-4173-8ec3-66ea73d009b6",
  "type": "document_action",
  "status": "succeeded",
  "progress": {
    "stage": "redline",
    "completed": 1,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": {
    "action": "redline",
    "file_ids": [
      "fa1967d0-cd93-4f48-86ab-448ecfb67f49"
    ],
    "summary": {
      "insertions": 3,
      "deletions": 3
    }
  },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T11:00:00Z",
  "updated_at": "2026-10-13T11:00:08Z",
  "completed_at": "2026-10-13T11:00:08Z"
}
```

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


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