API-Dokumentation

Alle Endpunkte, Parameter, Antwortformate und Credit-Kosten im Überblick.

Authentifizierung & Schnellstart

Base-URL

https://api.factsoft.de/v2

Alle Endpunkte dieser Dokumentation werden an diese Basis-URL angehängt. Die API ist ausschließlich per HTTPS erreichbar.

API-Key (Header)

Jeder Aufruf (außer Test-Endpunkte) benötigt einen API-Key im HTTP-Header:

X-API-Key: Ihr-api-key-hier

Beispiel – vollständiger Aufruf mit curl

curl -X POST https://api.factsoft.de/v2/depersonalize \ -H "X-API-Key: Ihr-api-key-hier" \ -H "Content-Type: application/json" \ -d '{"text": "Hallo Frau Schmitt, Ihre IBAN lautet DE22200400600056789001."}'

Ohne API-Key können Sie https://api.factsoft.de/v2/depersonalize/test aufrufen – dieser Endpunkt verbraucht keine Credits und erfordert keine Registrierung.

ℹ API-Keys erhalten Sie nach dem Kauf eines Pakets. Test-Endpunkte (/depersonalize/test, /process/test) verbrauchen keine Credits und benötigen keinen API-Key.
🛁 Datenschutz & DSGVO: Personenbezogene Daten verlassen das Depersonalisierungssystem zu keinem Zeitpunkt, werden auf den verarbeitenden Servern nicht gespeichert und bleiben vollständig in der EU. Mit jedem API-Key stellt factsoft AG eine DSGVO-konforme Auftragsverarbeiter-Vereinbarung (AVV) aus.

Credit-System

Credits werden pro API-Aufruf abgezogen:

EndpunktCredits
/depersonalize, /depersonalize/json, /depersonalize/csv1
/rehydrate, /rehydrate/json0 (kostenlos)
/process, /process/json, /process/csv1 (NER) + 1–10 (KI) = 2–11 Credits
/query1–10 Credits (nur KI, kein NER-Schritt)
Test-Endpunkte (/depersonalize/test, /process/test)0 (kein Key nötig)

Die KI-Credits bei /process und /query richten sich nach Textlänge und gewähltem Modell. Der exakte Wert wird vor dem Aufruf geprüft – sind nicht genug Credits vorhanden, wird der Aufruf abgelehnt. Jede Antwort enthält credits_used und credits_remaining.

KI-Credits nach Textlänge
TextlängeHaikuSonnet (default)
bis 2.000 Zeichen11
bis 5.000 Zeichen23
bis 10.000 Zeichen35
bis 15.000 Zeichen46
bis 20.000 Zeichen58
bis 30.000 Zeichen69
bis 40.000 Zeichen710
über 40.000 Zeichen8–1010

Bei /process kommen zu den KI-Credits immer +1 Credit für den NER-Anonymisierungsschritt hinzu.

Eingabe-Limits

EndpunktFeldMaximumFehler bei Überschreitung
/depersonalize, /depersonalize/json, /depersonalize/csv, /depersonalize/testtext60.000 Zeichen422
/process, /process/json, /process/csv, /process/test, /querytext40.000 Zeichen422
/process, /process/json, /process/csv, /queryinstruction2.000 Zeichen422
/processmax_output_tokens8.192 Tokens (Hardcap Claude-API)wird automatisch auf 8.192 gedeckelt

Wenn max_output_tokens nicht angegeben wird oder 0 ist, berechnet das System den optimalen Wert automatisch (ca. Eingabezeichen ÷ 3 × 1,25, mindestens 512 Tokens). Das verhindert abgeschnittene Antworten bei langen Texten. Der Wert wird in der Antwort als max_tokens_used zurückgegeben.

Funktion A – Depersonalisierung

POST /v2/depersonalize Text depersonalisieren ▶

Erkennt PII im Freitext und ersetzt sie durch typisierte Platzhalter. Gibt anonymisierten Text + Key zurück.

Request Body

FeldTypPflichtBeschreibung
textstring✓Zu anonymisierender Text (max. 60.000 Zeichen)
languagestring–Sprache: de (default) oder en
placeholder_stylestring–typed (default) oder generic
// Beispiel-Request { "text": "Hallo Frau Schmitt, IBAN DE22200400600056789001" } // Antwort { "anonymized_text": "Hallo PERSON_F_1, IBAN IBAN_1", "key": { "PERSON_F_1": "Frau Schmitt", "IBAN_1": "DE222..." }, "entity_count": 2, "credits_used": 2, "credits_remaining": 498 }
POST /v2/depersonalize/json JSON-Objekt depersonalisieren ▶

Verarbeitet beliebig verschachtelte JSON-Strukturen. Alle String-Werte werden anonymisiert, Integer und Booleans bleiben unverändert.

FeldTypPflichtBeschreibung
dataobject | array✓JSON-Objekt oder Array
fieldsstring[]–Nur diese Top-Level-Felder verarbeiten
{ "data": { "name": "Thomas Müller", "email": "t.mueller@example.com", "count": 42 } } // Antwort: { "anonymized_data": { "name": "PERSON_1", "email": "EMAIL_1", "count": 42 }, "key": { "PERSON_1": "Thomas Müller", "EMAIL_1": "t.mueller@example.com" }, "entity_count": 2 }
POST /v2/depersonalize/csv CSV-Datei depersonalisieren ▶

Nimmt eine CSV-Datei (Upload oder Rohtext) und gibt eine anonymisierte CSV zurück. Delimiter wird automatisch erkannt (, oder ;).

FeldTypBeschreibung
filemultipart/form-dataCSV-Datei (oder text)
textform stringCSV als Rohtext (alternativ zu file)
columnsform stringKommagetrennte Spaltenauswahl (leer = alle)
has_headerform boolHat die CSV eine Kopfzeile? (default: true)
# curl-Beispiel mit Datei-Upload curl -X POST https://api.factsoft.de/v2/depersonalize/csv \ -H "X-API-Key: IhrKey" \ -F "file=@kunden.csv" \ -F "columns=name,email"
POST /v2/depersonalize/test Testmodus – kein Credit-Abzug ▶

Ersetzt erkannte PII durch xxxx (keine Reversibilität, kein Key). Ideal zum Testen der Erkennungsleistung. Verbraucht 0 Credits, kein API-Key nötig. Limit: 60.000 Zeichen.

{ "text": "..." } // Antwort: { "masked_text": "Hallo xxxx, IBAN xxxx.", "entity_count": 2, "entities_by_type": { "PERSON_F": 1, "IBAN": 1 } }

Funktion B – Rehydrierung

POST /v2/rehydrate Platzhalter zurücksetzen – kostenlos ▶

Ersetzt alle Platzhalter im Text anhand des Keys aus der Depersonalisierungsantwort. Immer kostenlos.

{ "text": "Hallo PERSON_F_1, Ihre IBAN ist IBAN_1.", "key": { "PERSON_F_1": "Frau Schmitt", "IBAN_1": "DE22200400600056789001" } } // Antwort: { "result": "Hallo Frau Schmitt, Ihre IBAN ist DE22200400600056789001.", "replacements_made": 2 }
POST /v2/rehydrate/json JSON rehydrieren – kostenlos ▶

Wie /rehydrate, aber für JSON-Objekte. Durchläuft die Struktur rekursiv.

{ "data": { "kunde": "PERSON_1" }, "key": { "PERSON_1": "Max Müller" } }

Funktion C – KI-Verarbeitung

🛁 DSGVO-konform: Der Text wird zunächst auf unseren EU-Servern depersonalisiert. Nur der anonymisierte Text mit Platzhaltern (z.B. PERSON_1, IBAN_1) wird an Claude übertragen. Originaldaten verlassen unser System zu keinem Zeitpunkt und werden nicht gespeichert.
POST /v2/process Depersonalisieren → Claude → Rehydrieren ▶

Vollständiger Durchlauf: Text wird serverseitig anonymisiert, der anonymisierte Text an Claude gesendet, die Antwort rehydriert und zurückgegeben.

FeldTypPflichtBeschreibung
textstring✓Zu verarbeitender Text (max. 40.000 Zeichen)
instructionstring✓Anweisung an Claude, z.B. "Formuliere eine höfliche Antwort" (max. 2.000 Zeichen)
modelstring–KI-Modell: claude-haiku-4-5-20251001 oder claude-sonnet-4-6 (default). Haiku ist günstiger, Sonnet leistungsstärker.
languagestring–Sprache (default: de)
signaturestring–Signatur, die Claude am Ende anhängen soll
max_output_tokensinteger–Maximale Claude-Ausgabe in Tokens (0 = automatisch, max. 8.192). Wird in der Antwort als max_tokens_used zurückgegeben.
{ "text": "Sehr geehrter Herr Maier, ich möchte mein Konto DE89 3704 0044 0532 0130 00 kündigen.", "instruction": "Formuliere eine höfliche Kündigungsbestätigung.", "signature": "Mit freundlichen Grüßen\nIhr Support-Team" } // Intern: Text wird zuerst depersonalisiert (API-Server, EU) → anonymisierter Text an Claude → Antwort rehydriert // Antwort: { "result": "Sehr geehrter Herr Maier, wir bestätigen die Kündigung Ihres Kontos DE89 3704 0044...\n\nMit freundlichen Grüßen\nIhr Support-Team", "entity_count": 2, "credits_used": 4, "credits_remaining": 496 }
POST /v2/process/test Vorschau – 0 Credits (Claude wird nicht aufgerufen) ▶

Zeigt, welcher anonymisierte Text an Claude übertragen worden wäre. Nützlich zur Prüfung des Erkennungsergebnisses.

POST /v2/process/json JSON-Objekte durch Claude verarbeiten lassen ▶

Anonymisiert alle String-Felder im JSON serverseitig, sendet das anonymisierte JSON an Claude, rehydriert die Antwort.

POST /v2/process/csv CSV-Dateien durch Claude verarbeiten lassen ▶

Wie /process, verarbeitet aber CSV-Dateien. Kleine Batches (<20 Zeilen) werden gebündelt übertragen.

Account – /v2/me

GET /v2/me API-Key-Informationen und Guthaben ▶
// Antwort: { "credits": 842, "credits_total": 1000, "created_at": "2026-04-01T12:00:00Z", "last_used_at": "2026-04-12T08:10:00Z", "config": {} }

Modellauswahl – Haiku 4.5 vs. Sonnet 4.6

Alle Endpunkte, die Claude aufrufen (/process, /process/json, /process/csv, /query), akzeptieren einen optionalen model-Parameter. Wird er weggelassen, wird Sonnet 4.6 verwendet.

Modell-IDNameStärkenCredits (KI-Anteil)
claude-haiku-4-5-20251001Haiku 4.5Schnell, günstig – ideal für CSV, Listen und strukturierte Daten1–10 (staffelweise)
claude-sonnet-4-6Sonnet 4.6 (default)Leistungsstark – empfohlen für komplexe Freitexte, juristische Dokumente1–10 (staffelweise)

Beispiel (curl):

// Mit Haiku: curl -X POST https://api.factsoft.de/v2/process \ -H "Content-Type: application/json" \ -H "X-API-Key: DEIN_API_KEY" \ -d '{"text": "...", "instruction": "...", "model": "claude-haiku-4-5-20251001"}' // Mit Sonnet (default – model-Feld kann weggelassen werden): curl -X POST https://api.factsoft.de/v2/process \ -H "Content-Type: application/json" \ -H "X-API-Key: DEIN_API_KEY" \ -d '{"text": "...", "instruction": "...", "model": "claude-sonnet-4-6"}'

Ungültige Modell-IDs werden mit HTTP 422 abgewiesen. Die genaue Credit-Staffelung nach Textlänge finden Sie auf der Preisseite.

Erkennungs-Engine & Platzhalter-Stile

Alle Endpunkte verwenden ausschließlich Regex + NER kombiniert – es gibt keinen separaten Modus-Parameter mehr.

LayerTechnologieErkennt
Layer 1Regex (Pattern-Matching)IBAN, E-Mail, Telefon, Datum, IP, URL, Kreditkarte u. v. m.
Layer 2NER via spaCy (de_core_news_lg)Personennamen, Organisationen, Orte – auch Freinamen

Platzhalter-Stile

StilBeispielBeschreibung
typed (default)IBAN_1, PERSON_F_2Typ + laufende Nummer
genericENTITY_1Einheitlicher Platzhalter

Funktion D – KI-Direktanfrage

Sendet Text und Anweisung direkt an Claude – ohne vorherige Anonymisierung oder anschließende Rehydrierung. Geeignet für Texte ohne personenbezogene Daten. Kostet 3 Credits.

POST /v2/query 3 Credits · Direktanfrage an Claude

Request-Body (JSON):

FeldTypPflichtBeschreibung
textstringjaZu verarbeitender Text – max. 40.000 Zeichen
instructionstringjaAnweisung an Claude – max. 2.000 Zeichen
modelstringneinKI-Modell: claude-haiku-4-5-20251001 oder claude-sonnet-4-6 (default)
max_output_tokensintnein0 = automatisch (max. 8.192). Rückgabe als max_tokens_used
signaturestringneinWird unverändert ans Ende der Antwort angehängt

Antwort:

{ "result": "Antwort von Claude...", "credits_used": 3, "credits_remaining": 97, "max_tokens_used": 512 }

Beispiel:

curl -X POST https://api.factsoft.de/v2/query \ -H "Content-Type: application/json" \ -H "X-API-Key: DEIN_API_KEY" \ -d '{ "text": "Das Quartalsergebnis Q1 liegt bei 2,1 Mio. EUR.", "instruction": "Fasse den Text in einem Satz zusammen." }'

Erkennungstypen & Platzhalter

TypModusBeispiel
IBANRegexDE89 3704 0044 0532 0130 00
EMAILRegexmax@example.com
PHONE_DE, PHONE_INTLRegex+49 171 1234567
IP_ADDRESSRegex192.168.1.1
DATERegex12.04.2026 / 2026-04-12
CREDIT_CARDRegex4111 1111 1111 1111
STEUER_IDRegex12345678901
PASSPORTRegexC01X00T47
LICENSE_PLATERegexB-AB 1234
POSTCODE_DERegex10115
URLRegexhttps://example.com
SV_NUMMER_DERegex12123456A123
PASSWORDRegexpassword: geheim123 → nur Wert
API_KEYRegexapi_key=abc…xyz → nur Wert
USERNAMERegexusername: max → nur Wert
PERSON_M, PERSON_FRegex (Anrede)Herr Müller / Frau Schmidt
PER, ORG, LOCNER (spaCy)NLP-erkannte Personen/Org/Orte
CUSTOMalleBenutzerdefinierte Regex aus Key-Config

Fehlercodes

HTTPFehler-CodeBedeutung
400empty_textText ist leer oder fehlt
401missing_api_keyX-API-Key Header fehlt
401invalid_api_keyUngültiger oder inaktiver API-Key
402insufficient_creditsNicht genug Credits
422–Ungültige Request-Parameter (Pydantic-Validierung)
503claude_timeoutClaude hat nicht innerhalb von 30 s geantwortet
503claude_unavailableAnthropic-API nicht erreichbar
500internal_errorUnerwarteter Serverfehler
// Fehler-Antwortformat: { "detail": { "error": "insufficient_credits", "message": "Nicht genug Credits.", "credits": 0 } }