Anonymize

POST /v1/cortina/anonymize — schickt Originaltext durch die 4-Stage-Pipeline und gibt anonymisierten Text plus Entity-Liste zurück. Das Mapping (Original ↔ Pseudonym) lebt im verschlüsselten Redis- Envelope der Session.

Auth: Bearer Token erforderlich.

Query-Parameter

Name	Typ	Required	Beschreibung
`stages`	string (comma-list)	nein	Stage-Filter, z. B. `1,2` zum Skippen der LLM-Stages. Default: alle konfigurierten Stages.

Beispiel: ?stages=1,2,3 lässt Stage 4 (Adversarial-Loop) weg, was die Latenz um die ~2–12 s der Loop-Iterationen reduziert.

→ Stage-Trade-offs in der Pipeline-Doku.

Request-Body

Feld	Typ	Required	Beschreibung
`text`	string	ja	Der zu anonymisierende Text. Length-Bounds: `[1, 100_000]` Zeichen.
`session_id`	string (UUID)	ja	Bestehende, aktive Session. Gehört in den Body, nicht in einen Header.

Beispiel-Request

curl -sS -X POST 'https://api.tup-ai.de/v1/cortina/anonymize' \
  -H "Authorization: Bearer $TUP_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hans Müller, IBAN DE89 3704 0044 0532 0130 00, ruft +49 89 1234567 an.",
    "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f"
  }'

Mit Stage-Filter:

curl -sS -X POST 'https://api.tup-ai.de/v1/cortina/anonymize?stages=1,2' \
  -H "Authorization: Bearer $TUP_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "...", "session_id": "..." }'

Response (`200 OK`)

Feld	Typ	Beschreibung
`anonymized_text`	string	Text mit Platzhaltern, z. B. `[PERSON_1]`, `[DE_IBAN_1]`.
`entities`	array of `PiiEntity`	Eine Detail-Beschreibung pro gefundenem Span.
`session_id`	string (UUID)	Echo der Session — nützlich für Convenience-Pfade, in denen die Session implizit erstellt wurde.
`audit_flags`	array of string	Degradierte Pfade. Leer = vollständig durchgelaufen.

`PiiEntity`-Schema

Feld	Typ	Beschreibung
`entity_type`	string	z. B. `"PERSON"`, `"DE_IBAN"`, `"EMAIL_ADDRESS"`. Closed Set, siehe Pipeline.
`start`	integer	Start-Offset im Originaltext (UTF-16 Code Units).
`end`	integer	End-Offset im Originaltext (UTF-16 Code Units).
`placeholder`	string	Der eingesetzte Platzhalter, z. B. `"[PERSON_1]"`.
`confidence`	number	`[0, 1]`. Stage-1-Pattern-Treffer kommen mit `1.0`; spaCy-Treffer mit fester `0.85`.

Beispiel-Response

{
  "anonymized_text": "[PERSON_1], IBAN [DE_IBAN_1], ruft [DE_PHONE_NUMBER_1] an.",
  "entities": [
    {
      "entity_type": "PERSON",
      "start": 0,
      "end": 11,
      "placeholder": "[PERSON_1]",
      "confidence": 0.85
    },
    {
      "entity_type": "DE_IBAN",
      "start": 18,
      "end": 43,
      "placeholder": "[DE_IBAN_1]",
      "confidence": 1.0
    },
    {
      "entity_type": "DE_PHONE_NUMBER",
      "start": 51,
      "end": 66,
      "placeholder": "[DE_PHONE_NUMBER_1]",
      "confidence": 0.95
    }
  ],
  "session_id": "018f4a2c-3d7e-7b4a-8c1e-2f9b3d4e5a6f",
  "audit_flags": []
}

Audit-Flags

Wenn audit_flags nicht leer ist, lief die Pipeline degradiert. Caller mit Compliance-Anspruch sollten das als Signal werten.

Flag	Bedeutung
`context_llm_disabled`	Stage 3 per Config aus.
`context_llm_unavailable`	Stage 3 wollte laufen, Provider war down.
`adversarial_unavailable`	Stage 4 down.
`adversarial_invalid_output`	Stage 4 LLM zweimal nicht parsebar.
`re_id_risk_remaining`	Stage 4 lief, ε wurde nicht erreicht.
`re_id_oscillation`	Stage 3 ↔ 4 sind sich uneinig — Pipeline-Instabilität.

Error-Codes

HTTP	`code`	Wann
401	`unauthorized`	Auth-Header fehlt oder Key ungültig.
404	`session_not_found`	`session_id` existiert nicht (mehr) — etwa weil expired oder destroyed.
422	`validation_error`	`text` leer oder >100 000 Zeichen, `session_id` keine UUID, `stages` ungültig.
429	`rate_limit_exceeded`	Per-Key Rate-Limit erreicht. `Retry-After`-Header gibt Sekunden bis Reset.
503	(kein code)	Service-Restart / unhealthy. Retry mit Backoff.

session_expired wird als 404 session_not_found zurückgegeben — der Service unterscheidet im Public-API nicht zwischen „existiert nicht” und „existiert nicht mehr”, um Probing-Angriffe zu verhindern.