Redact File

curl -X POST "https://api.wordsmith.ai/api/v1/files/9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6/redact" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b4e2f6a-0d7c-4a19-b3e8-1c5f9a2d6e07" \
  -d '{
    "categories": ["names", "emails", "phone_numbers"],
    "terms": ["Project Kestrel"]
  }'

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "running",
  "progress": {
    "stage": "redact",
    "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
}

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "succeeded",
  "progress": {
    "stage": "redact",
    "completed": 1,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": {
    "action": "redact",
    "file_ids": [
      "e4ea249e-eb88-4e19-9ac2-bcfd2147357b"
    ],
    "summary": null
  },
  "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"
}

POST

api

files

{file_id}

redact

curl -X POST "https://api.wordsmith.ai/api/v1/files/9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6/redact" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b4e2f6a-0d7c-4a19-b3e8-1c5f9a2d6e07" \
  -d '{
    "categories": ["names", "emails", "phone_numbers"],
    "terms": ["Project Kestrel"]
  }'

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "running",
  "progress": {
    "stage": "redact",
    "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
}

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "succeeded",
  "progress": {
    "stage": "redact",
    "completed": 1,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": {
    "action": "redact",
    "file_ids": [
      "e4ea249e-eb88-4e19-9ac2-bcfd2147357b"
    ],
    "summary": null
  },
  "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"
}

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

Finds and blacks out the categories of information you choose, plus any exact terms you list. The output is a new PDF whose pages are flattened to images, so the redacted text cannot be recovered from the file. The original file is not changed. Pass at least one of categories or terms. 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

string (uuid)

required

The file to redact: a PDF, DOCX or DOC.

Headers

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

string[]

The kinds of information to find and redact. Any of:

Value	Redacts
`names`	Names of people
`emails`	Email addresses
`phone_numbers`	Phone numbers
`addresses`	Postal addresses
`financial`	Bank account, card and payment details, and monetary amounts
`identifiers`	Government, tax and company registration numbers

string[]

Up to 100 extra strings to redact wherever they appear, such as a project code name or a counterparty’s name. Matching ignores case.

integer

default:"0"

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

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": "redact", "file_ids", "summary" }. file_ids holds one id: the redacted PDF. summary is null. When status is failed, error.code says why:

`error.code`	When
`redaction_failed`	The redaction could not run, for example because no text could be read from the document. `error.message` says why.
`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.

string (uuid)

The operation’s id.

string

document_action.

string

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

object | null

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

object

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

object | null

Set when status is succeeded.

object | null

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

integer | null

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

string

ISO 8601 UTC.

string

ISO 8601 UTC.

string | null

ISO 8601 UTC, once the operation has finished.

curl -X POST "https://api.wordsmith.ai/api/v1/files/9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6/redact" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b4e2f6a-0d7c-4a19-b3e8-1c5f9a2d6e07" \
  -d '{
    "categories": ["names", "emails", "phone_numbers"],
    "terms": ["Project Kestrel"]
  }'

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "running",
  "progress": {
    "stage": "redact",
    "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
}

{
  "id": "2cb00fbc-da02-45c6-aa16-a4a07b2f2503",
  "type": "document_action",
  "status": "succeeded",
  "progress": {
    "stage": "redact",
    "completed": 1,
    "total": 1
  },
  "resource": {
    "type": "file",
    "id": "9a1d7e44-2b6c-4f08-8d3a-71c5e0b9f2a6"
  },
  "result": {
    "action": "redact",
    "file_ids": [
      "e4ea249e-eb88-4e19-9ac2-bcfd2147357b"
    ],
    "summary": null
  },
  "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 neither `categories` nor `terms` is set, or a category is not one of the values above.
400	`unsupported_file_type`	The file is not a PDF, DOCX or DOC.
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.

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

Path parameters

Headers

Body parameters

Response

Errors

​Authentication

​Path parameters

​Headers

​Body parameters

​Response

​Errors

Authentication

Path parameters

Headers

Body parameters

Response

Errors