# Redact personal data

Accepts up to 64 KiB of text. Detects the requested entity categories and replaces them
with collision-safe typed placeholders. Offsets count Unicode scalar values, end exclusive.
Native execution reserves characters; explicitly approved structured chat execution
reserves tokens before sending plaintext. LLMs return locations only, using bounded
overlapping windows; the gateway validates and masks them. Invalid entries are counted,
wholly unusable output fails closed or uses an authorized fallback. This endpoint always
fails closed. Original entity text and replacement maps are never persisted. Key/org
provider, country, jurisdiction and privacy requirements also apply to the detector.

`POST https://api.tokenlane.de/v1/pii/redact`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "API key as bearer token in the `Authorization` header: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Missing, unknown or expired keys get 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

## curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/pii/redact' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}'
```

## node

```node
const response = await fetch("https://api.tokenlane.de/v1/pii/redact", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/pii/redact",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/pii/redact", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}`,
});
console.log(await response.text());
```

## header: Idempotency-Key (optional)

Explicit opt-in to encrypted response replay across gateway nodes. One 1..=255 printable ASCII value per logical operation, scoped to this API key ID. Reuse the same method, path and normalized body. Completed responses are retained for at most 10 minutes; replay is free and creates no generation. Conflicting content or unavailable replay returns 409. A successful replay carries Idempotent-Replayed: true and preserves the original request and generation IDs. See /docs/guides/idempotency.

### s0: string | null

{}

## Body: application/json

```json
{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}
```

### s28: object

Detects personal information with an approved native detector or span-only LLM task.
LLM execution is a gateway extension: the selected model receives the original text,
returns checked locations only, and never supplies the masked text.

{}

```json
{
  "entities": [
    "email"
  ],
  "text": "Contact lena@example.invalid",
  "threshold": 0.5
}
```

- entities (optional): s351

### s351: array

Requested categories: person, address, email, phone, iban, identifier, date_of_birth,
organization. Defaults to all eight; null, duplicates and empty lists are rejected.

{"minItems":"1","maxItems":"8"}

```json
[
  "email"
]
```

### s7: string

{}

- model (optional): s352

### s352: string

Public model ID or alias; omitted selects the operator's default PII model.
A normal chat model needs an explicitly approved, bounded `pii.llm` route with
JSON Schema or forced-tool output. All model, provider and privacy policies apply.

{}

```json
"grunden/gliner-multi-pii"
```

- provider (optional): s353

### s353: object

Ordinary provider routing preferences, including EUR max_price.character.

{}

- text (required): s354

### s354: string

Nonempty input, at most 65536 UTF-8 bytes. Positions in the response count Unicode scalar values.

{"maxLength":"65536"}

```json
"Contact lena@example.invalid"
```

- threshold (optional): s355

### s355: number

Confidence from zero to one, default 0.5; rounded down to thousandths. Explicit null is rejected.

double

{"minimum":"0","maximum":"1"}

```json
0.5
```

## Response 200: application/json

Redacted text, validated spans and exact EUR usage

```json
{
  "entities": [
    {
      "end": 28,
      "entity": "email",
      "start": 8
    }
  ],
  "id": "gen-example",
  "masked": "Contact [EMAIL_nonce_1]",
  "model": "gliner-multi-pii",
  "usage": {
    "characters": 28,
    "cost": 5.6e-7,
    "currency": "EUR",
    "duration_ms": 23
  }
}
```

### s29: object

Typed redaction result. Neither this response nor its metadata repeats original entity text.

{}

```json
{
  "entities": [
    {
      "end": 28,
      "entity": "email",
      "start": 8
    }
  ],
  "id": "gen-example",
  "masked": "Contact [EMAIL_nonce_1]",
  "model": "gliner-multi-pii",
  "usage": {
    "characters": 28,
    "cost": 5.6e-7,
    "currency": "EUR",
    "duration_ms": 23
  }
}
```

- entities (required): s356

### s356: array

Validated, nonoverlapping spans sorted by start offset.

{}

### s180: object

A span in the original input, using Unicode scalar values and an exclusive end.

{}

```json
{
  "end": 28,
  "entity": "email",
  "start": 8
}
```

- end (required): s921

### s921: integer

First Unicode scalar value after the entity.

{"minimum":"0"}

```json
28
```

- entity (required): s922

### s922: string

Supported public category, independent of provider-specific labels.

{}

```json
"email"
```

- start (required): s923

### s923: integer

First Unicode scalar value of the entity.

{"minimum":"0"}

```json
8
```

- id (required): s357

### s357: string

Generation ID for subsequent cost and status lookup.

{}

```json
"gen-example"
```

- masked (required): s358

### s358: string

Text with unique typed placeholders, preserving all undetected characters.

{}

```json
"Contact [EMAIL_nonce_1]"
```

- model (required): s359

### s359: string

Configured detector model.

{}

```json
"gliner-multi-pii"
```

- usage (required): s360

### s360: object

Exact charge and detector timing, also retained if subsequent processing fails.

{}

```json
{
  "characters": 28,
  "cost": 5.6e-7,
  "currency": "EUR",
  "duration_ms": 23
}
```

- characters (required): s924

### s924: integer

Number of Unicode scalar values processed.

int64

{"minimum":"0"}

```json
28
```

- cost (required): s925

### s925: number

Exact detector charge: characters for native execution, confirmed tokens for LLMs.
GET /generation retains the execution, token usage and original-currency components.

double

{}

```json
5.6e-7
```

- currency (required): s926

### s926: string

Customer billing currency, always EUR.

{}

```json
"EUR"
```

- duration_ms (required): s927

### s927: integer

Detector round-trip duration in milliseconds.

int64

{"minimum":"0"}

```json
23
```

## Response 400: application/json

Invalid JSON or fields; all problems appear in metadata.issues

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Every response with an HTTP status of 400 or higher has this shape, OpenRouter's error
format. Everything the gateway adds is inside `error.metadata`, so OpenRouter clients see
nothing unfamiliar. See "Errors" in the introduction for all error types.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (required): s238

### s238: object

What went wrong.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (required): s633

### s633: integer

The HTTP status of the response, as a number.

int32

{"minimum":"0"}

```json
400
```

- message (required): s634

### s634: string

What went wrong, in English. With several problems: the first one and how many more
follow; all of them are in `metadata.issues`. The text may change; match on
`metadata.type` instead.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Details for programs: error type, request ID, every problem, a suggested fix and, for
provider errors, which provider failed. Always present on gateway errors.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Providers that serve the model (when `provider.only` excluded all of them).

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

- docs_url (required): s640

### s640: string

Link to the section of this error type in the documentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

The routing step that left no route (routing errors only).

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Every problem found in the request, so all can be fixed at once (at most 20); for
routing errors one entry per excluded route, for `no_provider_available` one per failed
attempt.

{}

### s123: object

One problem in the request, one reason a route was excluded, or one failed attempt.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (required): s636

### s636: string

Kind of problem, stable for programs.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (required): s637

### s637: string

The problem in English, naming the field and, if short, the value sent.

{}

```json
"temperature must be at most 2, got 5"
```

- path (required): s638

### s638: string

Where the problem is: JSONPath of the field in the request body, for example
`$.messages[2].content[0].image_url.url`, or `query.<name>` for a query parameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Safe provider diagnostics, identical for HTTP errors and terminal stream events.

{}

oneOf: s1158

### s1158: object

Provider diagnostics without provider-authored text. HTTP and terminal SSE errors use
this same structure; arbitrary upstream messages and metadata are discarded.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (required): s1299

### s1299: string

Gateway classification from HTTP status and recognized dialect identifiers.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exact identifier from the configured dialect's fixed list; arbitrary values vanish.

{}

```json
"rate_limit_exceeded"
```

- provider_name (required): s1301

### s1301: string

Configured provider name, never a name supplied by the upstream body.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Bounded seconds from the upstream Retry-After header, when present and numeric.

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s1303

### s1303: boolean

Whether the classified failure can be transient. Unknown failures are not promised retryable.

{}

- status (optional): s1304

### s1304: integer

Actual HTTP status received from the upstream, including 200 for native errors.
Absent when no HTTP status is available.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

The provider that failed, as in the response field `provider` (provider errors only).

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserved OpenRouter compatibility field. The gateway never fills it: provider
free text is deliberately withheld. Use provider_error instead.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

A concrete fix, for example the closest model ID to a mistyped one.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (required): s647

### s647: string

ID of the request, the same as the `x-request-id` response header. Quote it when
contacting support.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Providers named in `provider.only` (when it excluded all routes).

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Seconds to wait before retrying; also sent as the `Retry-After` header (429 and 503).

int64

{"minimum":"0"}

```json
2
```

- retryable (required): s650

### s650: boolean

Whether sending the identical request again can succeed (for example after a timeout
or rate limit), as opposed to errors that need a changed request.

{}

- routing_funnel (optional): s651

### s651: array

How routing narrowed down the providers: each step with the number of routes left
(routing errors only, same format as OpenRouter).

{}

### s200: object

One routing step, as in OpenRouter's `routing_funnel`.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (required): s979

### s979: integer

Number of routes (providers of the model) left after the step.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

The request field the step filtered on.

{}

```json
"provider.only"
```

- step (required): s981

### s981: string

Name of the step, as at OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (required): s652

### s652: string

Stable error type to match on in code; see "Errors" in the introduction. Messages may
change, the type does not.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organization of the API key, if the key was recognized.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Response 401: application/json

Missing, invalid or expired API key

## Response 402: application/json

Insufficient key or organization credit for detection

## Response 403: application/json

Organization, workspace or key policy forbids the configured detector model

## Response 404: application/json

No approved detector satisfies the data policy

## Response 408: application/json

Body or detector timeout

## Response 409: application/json

idempotency_conflict: this key has different request content; use a new key. idempotency_in_progress: the original is running; respect Retry-After. idempotency_unavailable: no safe replay is possible; do not silently recompute. See remedy_hint.

## Response 413: application/json

Request exceeds byte or parsed-memory bounds

## Response 429: application/json

Customer or provider quota exceeded

## Response 500: application/json

Unexpected internal error

## Response 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Response 502: application/json

Detector failed or returned invalid spans

## Response 503: application/json

Gateway busy or shutting down
