API-Dokumentation: Pseudonymisierung und Re-Identifikation
Basis-URL: https://persona-api.mind-verse.de · Alle Endpunkte erwarten und liefern JSON (UTF-8).
Authentifizierung
Jede Anfrage trägt Ihren API-Key als Bearer-Token. Keys erstellen Sie im Dashboard; gespeichert wird nur ein SHA-256-Hash.
Authorization: Bearer ps_live_…
POST /v1/pseudonymize
Erkennt PII und ersetzt jede Entität durch ein konsistentes Token (⟨PERSON_1⟩). Identische Werte erhalten dasselbe Token. Die API ist zustandslos — das Mapping existiert nur in der Antwort.
| Feld | Typ | Beschreibung |
|---|---|---|
| text | string (erforderlich) | Eingabetext, max. 60.000 Zeichen. Kurze Texte (< 6.000 Zeichen) unter 4s; lange Dokumente werden intern in überlappende Abschnitte zerlegt, damit auch bei mehrseitigen Verträgen nichts unerkannt bleibt — dafür wächst die Latenz mit der Länge (60.000 Zeichen ≈ 40s). |
Antwort
| Feld | Typ | Beschreibung |
|---|---|---|
| masked | string | Text mit Pseudonym-Tokens statt PII. |
| spans[] | object[] | Erkannte Entitäten: label, token, start, end, score (0–1), text. |
| mapping | object | Token → Originalwert. Für die Re-Identifikation aufbewahren — Persona speichert es nicht. |
| sensitivity | number | Gesamtsensibilität des Textes (0.0–1.0), z. B. fürs Modell-Routing. |
| latency_ms | number | Verarbeitungszeit auf dem Server. |
POST /v1/reidentify
Ersetzt Pseudonym-Tokens in einem Text (typischerweise der LLM-Antwort) wieder durch die Originalwerte aus dem Mapping.
| Feld | Typ | Beschreibung |
|---|---|---|
| text | string (erforderlich) | Text mit Pseudonym-Tokens. |
| mapping | object (erforderlich) | Das Mapping aus /v1/pseudonymize. |
PII-Kategorien
| Label | Token | Beispiele |
|---|---|---|
| private_person | ⟨PERSON_n⟩ | Namen natürlicher Personen |
| private_email | ⟨EMAIL_n⟩ | E-Mail-Adressen |
| private_phone | ⟨PHONE_n⟩ | Telefonnummern (alle Formate) |
| private_address | ⟨ADDRESS_n⟩ | Straße, PLZ, Wohnort |
| private_url | ⟨URL_n⟩ | persönliche Links & Profile |
| private_date | ⟨DATE_n⟩ | Geburtsdaten, identifizierende Termine |
| account_number | ⟨ACCOUNT_n⟩ | IBAN, Kunden-/Versichertennummern |
| secret | ⟨SECRET_n⟩ | API-Keys, Passwörter, Tokens |
| other_pii | ⟨PII_n⟩ | Kennzeichen, Ausweisnummern u. a. |
Fehlercodes
| Status | Bedeutung | Abhilfe |
|---|---|---|
| 401 | Key fehlt, ist ungültig oder widerrufen | Key im Dashboard prüfen |
| 402 | Monatskontingent erreicht oder Abo inaktiv | Upgrade unter /app/billing |
| 422 | Ungültiger Request-Body | Felder gegen diese Referenz prüfen |
| 429 | Rate-Limit erreicht (Starter 5 req/s, Pro 100 req/s) | Anfragen drosseln / Backoff |
Beispiele
# Text pseudonymisieren
curl https://persona-api.mind-verse.de/v1/pseudonymize \
-H "Authorization: Bearer $PERSONA_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Rückruf für Jonas Bergmann unter 0176 22558899."
}'import requests
r = requests.post(
"https://persona-api.mind-verse.de/v1/pseudonymize",
headers={"Authorization": f"Bearer {KEY}"},
json={"text": prompt},
)
data = r.json()
# pseudonymisierten Text ans LLM schicken …
antwort = llm(data["masked"])
# … und die Antwort re-identifizieren
for token, original in data["mapping"].items():
antwort = antwort.replace(token, original)const res = await fetch("https://persona-api.mind-verse.de/v1/pseudonymize", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PERSONA_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ text: prompt }),
});
const { masked, mapping, sensitivity } = await res.json();
// sensible Anfragen automatisch umleiten
const model = sensitivity > 0.8 ? onPremModel : cloudModel;
const antwort = await model.complete(masked);→ Antwort: { "masked", "spans[]", "mapping", "sensitivity" } — identisch zum Playground.
Fine-Tuning-Dataset (JSONL)
Ein Beispiel pro Zeile: text plus spans mit zeichengenauen Positionen. Eigene Labels (z. B. case_number) sind erlaubt.
{"text": "Az. 4 C 213/26, Kläger Jonas Bergmann", "spans": [
{"start": 0, "end": 14, "label": "case_number"},
{"start": 23, "end": 37, "label": "private_person"}
]}Noch Fragen?
Support unter persona@mind-verse.de — Pro-Kunden erhalten Antwort innerhalb von 24 Stunden.
Jetzt kostenlos starten →