API-Dokumentation

Die DatOnym REST-API anonymisiert Text (Prompts) und stellt die Originaldaten später wieder her. Sie eignet sich, um Anonymisierung direkt in eigene Anwendungen, Chatbots oder Middleware einzubauen.

Basis-URL

https://datonym.it-s.de/api/v1

Authentifizierung

Alle schreibenden Endpunkte erfordern einen API-Schlüssel im HTTP-Header:

X-API-Key: dein-api-schluessel

Den Schlüssel erhältst du vom Betreiber. GET /health und GET /entities sind ohne Schlüssel erreichbar. Die eigene Web-Oberfläche nutzt die API per Same-Origin und benötigt keinen Schlüssel.

Rate-Limit

Standardmäßig 120 Anfragen pro Minute und Schlüssel. Bei Überschreitung antwortet die API mit 429 rate_limited.

Endpunkte

Methode	Pfad	Zweck
POST	/anonymize	Text anonymisieren, Tokens erzeugen
POST	/deanonymize	Tokens wieder durch Klartext ersetzen
DELETE	/session/:id	Zuordnung sofort löschen
GET	/entities	Unterstützte Entitätstypen
GET	/health	Statusprüfung

POST /anonymize

Erkennt personenbezogene Daten und ersetzt sie durch stabile Tokens. Die Zuordnung (Mapping) wird verschlüsselt gespeichert und über die zurückgegebene session_id referenziert.

Anfrage

{
  "text": "Herr Thomas Lauer, thomas@lauer.io, IBAN DE02120300000000202051"
}

Antwort 200

{
  "session_id": "9c6153e7-aa66-433e-8ccb-67b26d13e17f",
  "anonymized_text": "Herr [[NAME_1]], [[EMAIL_1]], IBAN [[IBAN_1]]",
  "entities": [
    { "entity_type": "PERSON", "start": 5, "end": 17, "score": 0.85,
      "token": "[[NAME_1]]", "text": "Thomas Lauer" },
    { "entity_type": "IBAN", "start": 41, "end": 63, "score": 0.99,
      "token": "[[IBAN_1]]", "text": "DE02120300000000202051" }
  ],
  "mapping": [
    { "token": "[[NAME_1]]", "entity_type": "PERSON", "value": "Thomas Lauer" },
    { "token": "[[IBAN_1]]", "entity_type": "IBAN", "value": "DE02120300000000202051" }
  ],
  "stats": { "entityCount": 3, "uniqueTokens": 3, "anonymizationRate": 78, "dataLoss": 49 }
}

Hinweis: mapping und entities[].text enthalten Klartext. Wer zustandslos arbeiten möchte, speichert das mapping selbst und verwirft die session_id.

POST /deanonymize

Ersetzt Tokens wieder durch die Originalwerte („Personalisieren"). Zwei Modi:

Mandantentrennung: Eine per session_id gespeicherte Zuordnung ist an den erzeugenden API-Schlüssel gebunden. Sie kann nur mit demselben Schlüssel aufgelöst oder gelöscht werden – fremde Zugriffe erhalten 404.

a) Mit gespeicherter Session

{
  "session_id": "9c6153e7-aa66-433e-8ccb-67b26d13e17f",
  "text": "Guten Tag [[NAME_1]], Ihre IBAN [[IBAN_1]] ist notiert."
}

b) Zustandslos mit eigenem Mapping

{
  "text": "Guten Tag [[NAME_1]] ...",
  "mapping": [ { "token": "[[NAME_1]]", "value": "Thomas Lauer" } ]
}

Antwort 200

{ "text": "Guten Tag Thomas Lauer, Ihre IBAN DE02120300000000202051 ist notiert." }

DELETE /session/:id

Löscht die gespeicherte Zuordnung sofort (Recht auf Löschung). Antwort: { "deleted": true }.

GET /entities

Liefert die unterstützten Entitätstypen und ihr Token-Schema.

Typ	Token	Beschreibung
PERSON	[[NAME_n]]	Personennamen
EMAIL_ADDRESS	[[EMAIL_n]]	E-Mail-Adressen
PHONE_NUMBER	[[TEL_n]]	Telefonnummern
IBAN	[[IBAN_n]]	IBAN (mod-97-geprüft)
CREDIT_CARD	[[KARTE_n]]	Kreditkarten (Luhn-geprüft)
IP_ADDRESS	[[IP_n]]	IPv4/IPv6
STEUER_ID	[[STEUERID_n]]	Steuer-Identifikationsnummer
STEUERNUMMER	[[STEUERNR_n]]	Steuernummer (Finanzamt, z. B. 156/789/01234)
SV_NUMMER	[[SVNR_n]]	Sozialversicherungsnummer
KFZ_KENNZEICHEN	[[KFZ_n]]	KFZ-Kennzeichen
DATE	[[DATUM_n]]	Datum / Geburtsdatum
LOCATION	[[ORT_n]]	Adresse / PLZ + Ort
URL	[[URL_n]]	Web-Adressen

Fehlercodes

Status	error	Bedeutung
400	bad_request	Pflichtfeld fehlt / ungültig
400	reserved_token	Text enthält reservierte Token-Sequenzen [[TYP_1]]
401	unauthorized	API-Schlüssel fehlt/ungültig
404	session_not_found	Session unbekannt/abgelaufen
413	too_large	Text zu groß (max. 100.000 Zeichen)
429	rate_limited	Rate-Limit überschritten
500	internal	Interner Serverfehler

Beispiele

curl

curl -X POST https://datonym.it-s.de/api/v1/anonymize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DATONYM_KEY" \
  -d '{"text":"Herr Thomas Lauer, thomas@lauer.io"}'

JavaScript (fetch)

const res = await fetch("https://datonym.it-s.de/api/v1/anonymize", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": process.env.DATONYM_KEY },
  body: JSON.stringify({ text: "Herr Thomas Lauer, thomas@lauer.io" }),
});
const data = await res.json();
console.log(data.anonymized_text);

Python (requests)

import os, requests

r = requests.post(
    "https://datonym.it-s.de/api/v1/anonymize",
    headers={"X-API-Key": os.environ["DATONYM_KEY"]},
    json={"text": "Herr Thomas Lauer, thomas@lauer.io"},
)
print(r.json()["anonymized_text"])

Maschinenlesbare Spezifikation: openapi.yaml (OpenAPI 3.0).