> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.blende.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.blende.dev/_mcp/server.

# Redact a file

POST https://api.blende.dev/api/v1/files/redact
Content-Type: multipart/form-data

Redacts a TXT, DOCX or PDF file and answers its text redacted, or with `output: "file"` the redacted file too.

Reference: https://docs.blende.dev/api-reference/redact-and-restore/redact-a-file

## Authentication

- `Authorization` header (bearer token, required) — An API key: `Authorization: Bearer bl_live_…`.
- `Authorization` header (bearer token, required) — Blende's apps: a sign-in JWT, sent with `Blende-Context-Key`.

## Request

### Headers

- `Blende-Context-Key` (string, optional) — JWT only: the user's context key, 43 base64url characters.

### Body (multipart/form-data)

This endpoint expects a multipart form containing a file.

- `file` (file, required) — A TXT, DOCX or PDF file of at most 10 MB; never stored.
- `options` (FileRedactOptions, optional)

## Response

### 200

The redacted text as JSON, or `multipart/mixed` with the redacted file.

- `redacted_text` (string, required) — The redacted text.
- `tokens` (integer, required) — The text's billed tokens.
- `expires_at` (datetime, optional) — When the stored mapping expires (24 hours).
- `entities` (list of Entity, optional) — The mapping, with `store_entity_mapping: false` or `detailed: true`.
- `spans` (list of Span, optional) — With `detailed: true`: every finding.
- `model` (enum, optional) — With `detailed: true`: the model that answered.
  - Allowed values: `outis-flash-1`, `outis-1`

## Errors

### 400 Bad Request Error

`invalid_context_key`, `invalid_request`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 401 Unauthorized Error

`unauthenticated`, `key_expired`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 402 Payment Required Error

`quota_exceeded`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 403 Forbidden Error

`insufficient_scope`, `context_key_mismatch`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 404 Not Found Error

`policy_not_found`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 413 Content Too Large Error

`text_too_large`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 415 Unsupported Media Type Error

`unsupported_media_type`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 429 Too Many Requests Error

`rate_limited`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 500 Internal Server Error

`internal`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

### 503 Service Unavailable Error

`model_busy`, `store_full`.

- `type` (string, required) — `https://blende.dev/errors/<code>`.
- `title` (string, required) — A short summary of the code.
- `status` (integer, required) — The HTTP status.
- `code` (enum, required) — The stable error code.
  - Allowed values: `invalid_request`, `invalid_context_key`, `invalid_rule`, `invalid_pattern`, `too_many_patterns`, `too_many_matches`, `unauthenticated`, `key_expired`, `quota_exceeded`, `insufficient_scope`, `context_key_mismatch`, `policy_read_only`, `not_found`, `policy_not_found`, `text_too_large`, `unsupported_media_type`, `rate_limited`, `internal`, `model_busy`, `store_full`
- `request_id` (string, required) — The request's id, also in the `Request-Id` header.
- `detail` (string, optional) — What went wrong; never echoes input.
- `errors` (list of ProblemErrorsItems, optional) — Field errors, each pointing to a field of the schema.

## Types

### Entity

A tag and the value it stands for.

- `tag` (string, required) — `[KIND_ID]`: the kind, then 8 Crockford base32 characters.
- `kind` (EntityKind, required) — The entity's kind.
- `value` (string, required) — The original value; case counts.

### Span

One finding, hidden or shown.

- `kind` (SpanKind, required) — What the span is.
- `original_range` (Range, required) — Where it is in `text`.
- `output_range` (Range, required) — Where it is in `redacted_text`.
- `hidden` (boolean, required) — `false` when shown: a kept part, a leave or an uncertain span.
- `uncertain` (boolean, required) — The model was unsure; `false` for a rule's span.
- `tag` (string, required, nullable) — The entity's tag; `null` for a kept part or with `replace: "kind"`.
- `parts` (list of Part, required) — The span's parts, in the original text.

### ProblemErrorsItems

One field error.

- `pointer` (string, required) — The schema field, e.g. `#/redaction_policy/overrides/0/match/pattern`.
- `detail` (string, required) — What is wrong with it.

### EntityKind

The entity's kind.

- Kind: enum
  - Allowed values: `person`, `username`, `location`, `organization`, `occupation`, `address`, `email`, `phone`, `ip`, `iban`, `fax`, `url`, `date`, `date_of_birth`, `age`, `credit_card`, `card_expiry`, `card_security_code`, `tax_id`, `social_security`, `health_insurance`, `passport`, `id_card`, `customer_number`, `password`, `pin`, `api_key`, `delivery_number`, `order_number`, `invoice_number`, `case_number`, `product_number`, `price`, `salary`, `balance`, `bank_account`, `driving_licence`, `vehicle_plate`, `employee_number`, `student_number`, `coordinates`, `nationality`, `gender`, `file_path`, `other_number`, `product_name`
- enum
  - Allowed values: `custom`

### SpanKind

What the span is.

- Kind: enum
  - Allowed values: `person`, `username`, `location`, `organization`, `occupation`, `address`, `email`, `phone`, `ip`, `iban`, `fax`, `url`, `date`, `date_of_birth`, `age`, `credit_card`, `card_expiry`, `card_security_code`, `tax_id`, `social_security`, `health_insurance`, `passport`, `id_card`, `customer_number`, `password`, `pin`, `api_key`, `delivery_number`, `order_number`, `invoice_number`, `case_number`, `product_number`, `price`, `salary`, `balance`, `bank_account`, `driving_licence`, `vehicle_plate`, `employee_number`, `student_number`, `coordinates`, `nationality`, `gender`, `file_path`, `other_number`, `product_name`
- enum
  - Allowed values: `custom`

### Range

A half-open `[start, end)` range in code points of the text as sent.

- `start` (integer, required) — The first code point, inclusive.
- `end` (integer, required) — The code point after the last, exclusive.

### Part

A labelled part of a span, in the original text.

- `start` (integer, required) — The first code point, inclusive.
- `end` (integer, required) — The code point after the last, exclusive.
- `label` (enum, required) — The part's label.
  - Allowed values: `first_name`, `last_name`, `initials`, `suffix`, `placeholder`, `nickname`, `name_unclear`, `salutation`, `title`, `street`, `house_number`, `po_box`, `unit`, `postcode`, `district`, `city`, `region`, `country`, `landmark`, `address_unclear`, `natural_feature`, `location_unclear`, `org_name`, `legal_form`, `org_type`, `organization_unclear`

## Examples

**Request**

```json
{
  "file": "<file: letter.docx>",
  "options": {
    "output": "text"
  }
}
```

**Response**

```json
{
  "redacted_text": "[PERSON_7K2QX9MB] ([EMAIL_D3W8Q1TA]) wohnt in der [ADDRESS_P4N6V2RE], Berlin.",
  "tokens": 21,
  "expires_at": "2026-11-22T14:00:00Z"
}
```

**SDK Code**

```python A DOCX letter, output "text"
import requests

url = "https://api.blende.dev/api/v1/files/redact"

files = { "file": "open('letter.docx', 'rb')" }
payload = { "options": "{
  \"output\": \"text\"
}" }
headers = {"Authorization": "Bearer <apiKey>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript A DOCX letter, output "text"
const url = 'https://api.blende.dev/api/v1/files/redact';
const form = new FormData();
form.append('file', 'letter.docx');
form.append('options', '{
  "output": "text"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <apiKey>'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```