# Personenbezogene Daten schwärzen

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`

## Authentifizierung

[
  [
    {
      "name": "Authorization",
      "description": "API-Key als Bearer-Token im Header `Authorization`: `Authorization: Bearer sk-tl-v1-…`. Bestehende `sk-eu-`-Keys bleiben gültig. Fehlende, unbekannte oder abgelaufene Keys erhalten 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)

Ausdrückliches Opt-in zur verschlüsselten Antwortwiederholung über alle Gateway-Knoten. Ein Wert aus 1 bis 255 druckbaren ASCII-Zeichen pro logischem Vorgang, begrenzt auf die Identität dieses API-Keys. Methode, Pfad und normalisierten Body unverändert wiederholen. Abgeschlossene Antworten bleiben höchstens zehn Minuten verfügbar; eine Wiederholung ist kostenlos und erzeugt keine neue Generierung. Abweichender Inhalt oder eine nicht sicher wiederholbare Antwort ergibt 409. Eine erfolgreiche Wiederholung enthält Idempotent-Replayed: true und erhält die ursprünglichen Request- und Generation-IDs. Siehe /docs/guides/idempotency.

### s0: string | null

{}

## Anfrageinhalt: 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

Angeforderte Kategorien: person, address, email, phone, iban, identifier, date_of_birth, organization. Standardmäßig alle acht. Null, Duplikate und leere Listen werden abgelehnt.

{"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 (Pflichtfeld): s354

### s354: string

Nicht leere Eingabe mit höchstens 65536 UTF-8-Bytes. Positionen in der Antwort zählen Unicode-Skalarwerte.

{"maxLength":"65536"}

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

- threshold (optional): s355

### s355: number

Konfidenz zwischen null und eins, standardmäßig 0,5. Wird auf Tausendstel abgerundet. Explizites Null wird abgelehnt.

double

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

```json
0.5
```

## Antwort 200: application/json

Geschwärzter Text, validierte Bereiche und exakte EUR-Nutzungsdaten

```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

Typisiertes Schwärzungsergebnis. Weder die Antwort noch ihre Metadaten wiederholen den ursprünglichen Entitätstext.

{}

```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 (Pflichtfeld): s356

### s356: array

Validierte, nicht überlappende Bereiche, sortiert nach Anfangsposition.

{}

### s180: object

Ein Bereich der ursprünglichen Eingabe, gezählt in Unicode-Skalarwerten mit exklusivem Ende.

{}

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

- end (Pflichtfeld): s921

### s921: integer

Erster Unicode-Skalarwert nach der Entität.

{"minimum":"0"}

```json
28
```

- entity (Pflichtfeld): s922

### s922: string

Unterstützte öffentliche Kategorie, unabhängig von Provider-spezifischen Bezeichnungen.

{}

```json
"email"
```

- start (Pflichtfeld): s923

### s923: integer

Erster Unicode-Skalarwert der Entität.

{"minimum":"0"}

```json
8
```

- id (Pflichtfeld): s357

### s357: string

Generierungs-ID zum späteren Abrufen von Kosten und Status.

{}

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

- masked (Pflichtfeld): s358

### s358: string

Text mit eindeutigen typisierten Platzhaltern. Alle nicht erkannten Zeichen bleiben erhalten.

{}

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

- model (Pflichtfeld): s359

### s359: string

Konfiguriertes Detektormodell.

{}

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

- usage (Pflichtfeld): s360

### s360: object

Exakte Kosten und Detektorlaufzeit. Bleiben auch bei einem nachfolgenden Verarbeitungsfehler erhalten.

{}

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

- characters (Pflichtfeld): s924

### s924: integer

Anzahl verarbeiteter Unicode-Skalarwerte.

int64

{"minimum":"0"}

```json
28
```

- cost (Pflichtfeld): 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 (Pflichtfeld): s926

### s926: string

Abrechnungswährung des Kunden. Immer EUR.

{}

```json
"EUR"
```

- duration_ms (Pflichtfeld): s927

### s927: integer

Dauer des Detektoraufrufs einschließlich Rückweg in Millisekunden.

int64

{"minimum":"0"}

```json
23
```

## Antwort 400: application/json

Ungültiges JSON oder ungültige Felder. Alle Probleme stehen unter 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

Jede Antwort mit HTTP-Status ab 400 hat diese Struktur im Fehlerformat von OpenRouter. Alle Gateway-Erweiterungen stehen unter `error.metadata`, damit OpenRouter-Clients keine unbekannte äußere Struktur erhalten. Der Abschnitt „Fehler“ in der Einführung nennt alle Fehlertypen.

{}

```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 (Pflichtfeld): s238

### s238: object

Fehlerbeschreibung.

{}

```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 (Pflichtfeld): s633

### s633: integer

HTTP-Status der Antwort als Zahl.

int32

{"minimum":"0"}

```json
400
```

- message (Pflichtfeld): s634

### s634: string

Fehlerbeschreibung auf Englisch. Bei mehreren Problemen werden das erste und die Anzahl weiterer genannt. Alle stehen unter `metadata.issues`. Der Text kann sich ändern. Im Code stattdessen `metadata.type` auswerten.

{}

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

- metadata (optional): s635

### s635: object

Maschinenlesbare Details: Fehlertyp, Anfrage-ID, alle Probleme, ein Lösungsvorschlag und bei Provider-Fehlern der betroffene Provider. Bei Gateway-Fehlern immer vorhanden.

{}

```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

Provider, die das Modell anbieten, wenn `provider.only` alle ausgeschlossen hat.

{}

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

- docs_url (Pflichtfeld): s640

### s640: string

Link zum Abschnitt dieses Fehlertyps in der Dokumentation.

{}

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

- failed_routing_step (optional): s641

### s641: string

Routing-Schritt, nach dem keine Route übrig blieb. Nur bei Routing-Fehlern.

{}

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

- issues (optional): s642

### s642: array

Alle erkannten Probleme der Anfrage, damit sie gemeinsam behoben werden können. Höchstens 20 Einträge. Bei Routing-Fehlern ein Eintrag je ausgeschlossener Route, bei `no_provider_available` einer je fehlgeschlagenem Versuch.

{}

### s123: object

Ein Anfrageproblem, ein Ausschlussgrund einer Route oder ein fehlgeschlagener Versuch.

{}

```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 (Pflichtfeld): s636

### s636: string

Art des Problems. Für Programme stabil.

"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 (Pflichtfeld): s637

### s637: string

Problembeschreibung auf Englisch mit dem Feld und, sofern kurz, dem gesendeten Wert.

{}

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

- path (Pflichtfeld): s638

### s638: string

Position des Problems: JSONPath des Felds im Anfrageinhalt, beispielsweise `$.messages[2].content[0].image_url.url`, oder `query.<name>` bei einem Abfrageparameter.

{}

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

- provider_error (optional): s643

### s643: oneOf

Sichere Provider-Diagnosen, einheitlich für HTTP-Fehler und finale Stream-Ereignisse.

{}

oneOf: s1158

### s1158: object

Provider-Diagnosen ohne vom Provider verfassten Text. HTTP-Fehler und finale SSE-Fehler verwenden dieselbe Struktur. Beliebige Upstream-Meldungen und Metadaten werden verworfen.

{}

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

- category (Pflichtfeld): s1299

### s1299: string

Gateway-Klassifizierung anhand von HTTP-Status und erkannten Dialektkennungen.

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

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exakte Kennung aus der festen Liste des konfigurierten Dialekts. Beliebige andere Werte werden entfernt.

{}

```json
"rate_limit_exceeded"
```

- provider_name (Pflichtfeld): s1301

### s1301: string

Konfigurierter Provider-Name. Nie ein Name aus dem Upstream-Antwortinhalt.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Begrenzte Wartezeit in Sekunden aus dem Upstream-Header Retry-After, sofern vorhanden und numerisch.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s1303

### s1303: boolean

Ob der klassifizierte Fehler vorübergehend sein kann. Bei unbekannten Fehlern wird ein sinnvoller erneuter Versuch nicht zugesichert.

{}

- status (optional): s1304

### s1304: integer

Tatsächlich vom Upstream empfangener HTTP-Status, einschließlich 200 bei nativen Fehlern. Fehlt, wenn kein HTTP-Status verfügbar ist.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

Fehlgeschlagener Provider wie im Antwortfeld `provider`. Nur bei Provider-Fehlern.

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserviertes Feld für OpenRouter-Kompatibilität. Das Gateway befüllt es nie. Freier Provider-Text wird bewusst nicht ausgegeben. Stattdessen provider_error verwenden.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

Ein konkreter Lösungsvorschlag, beispielsweise die ähnlichste Modell-ID bei einem Tippfehler.

{}

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

- request_id (Pflichtfeld): s647

### s647: string

Anfrage-ID. Identisch mit dem Antwortheader `x-request-id`. Diese ID bei Supportanfragen angeben.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Unter `provider.only` genannte Provider, wenn dadurch alle Routen ausgeschlossen wurden.

{}

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

- retry_after (optional): s649

### s649: integer

Wartezeit vor einem erneuten Versuch in Sekunden. Wird bei 429 und 503 auch als Header `Retry-After` gesendet.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s650

### s650: boolean

Ob dieselbe unveränderte Anfrage bei einem erneuten Versuch erfolgreich sein kann, beispielsweise nach einer Zeitüberschreitung oder einem Anfragelimit. Im Gegensatz zu Fehlern, die eine geänderte Anfrage erfordern.

{}

- routing_funnel (optional): s651

### s651: array

Eingrenzung der Provider durch das Routing. Jeder Schritt nennt die Anzahl verbleibender Routen. Nur bei Routing-Fehlern, im selben Format wie bei OpenRouter.

{}

### s200: object

Ein Routing-Schritt wie unter `routing_funnel` von OpenRouter.

{}

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

- endpoint_count (Pflichtfeld): s979

### s979: integer

Anzahl der nach diesem Schritt verbleibenden Routen beziehungsweise Modell-Provider.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

Anfragefeld, nach dem der Schritt gefiltert hat.

{}

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

- step (Pflichtfeld): s981

### s981: string

Name des Schritts wie bei OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (Pflichtfeld): s652

### s652: string

Stabiler Fehlertyp für die Auswertung im Code. Siehe „Fehler“ in der Einführung. Meldungen können sich ändern, der Typ bleibt stabil.

"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

Organisation des API-Keys, sofern der Key erkannt wurde.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Antwort 401: application/json

API-Key fehlt, ist ungültig oder abgelaufen.

## Antwort 402: application/json

Guthaben des Keys oder der Organisation reicht für die Erkennung nicht aus.

## Antwort 403: application/json

Die Richtlinie der Organisation, des Arbeitsbereichs oder des Schlüssels verbietet das konfigurierte Detektormodell

## Antwort 404: application/json

Kein freigegebener Detektor erfüllt die Datenregeln.

## Antwort 408: application/json

Zeitüberschreitung beim Anfrageinhalt oder Detektor

## Antwort 409: application/json

idempotency_conflict: Der Key gehört zu anderem Anfrageinhalt; einen neuen Key verwenden. idempotency_in_progress: Der ursprüngliche Vorgang läuft noch; Retry-After beachten. idempotency_unavailable: Eine sichere Wiederholung ist nicht möglich; nicht still neu berechnen lassen. remedy_hint beachten.

## Antwort 413: application/json

Anfrage überschreitet Byte- oder Parserspeichergrenzen.

## Antwort 429: application/json

Kontingent des Kunden oder Providers überschritten

## Antwort 500: application/json

Unerwarteter interner Fehler

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

## Antwort 502: application/json

Detektor fehlgeschlagen oder ungültige Bereiche zurückgegeben

## Antwort 503: application/json

Gateway ausgelastet oder wird beendet
