Dokumentation der API
Vollständige REST-API-Referenz für die selbst gehostete promptShield-Engine. Alle Endpunkte sind unter der URL Ihrer Bereitstellung verfügbar.
Basis-URL
http://localhost:8000Ersetzen Sie sie durch Host und Port Ihrer Bereitstellung.
OpenAPI-Schema
Der Server stellt /docs (Swagger UI), /redoc und /openapi.json bereit. Im API-Schlüssel-Modus verlangen alle drei den Authorization-Header, ein Browser kann sie also nicht direkt öffnen. Holen Sie das Schema und laden Sie es in einen Client, der Header senden kann:
curl -H "Authorization: Bearer $PROMPTSHIELD_API_KEY" \
http://localhost:8000/openapi.json -o promptshield-openapi.jsonEin Browser kann den Authorization-Header bei einer Navigation nicht mitsenden, deshalb antwortet /docs im API-Schlüssel-Modus mit 401. Nutzen Sie stattdessen das Schema oben.
Authentifizierung
Wenn PROMPTSHIELD_API_KEY gesetzt ist (über promptshield serve --api-key oder die Docker-Umgebungsvariable), muss jede Anfrage ihn als Authorization: Bearer <api-key> mitsenden; fehlende oder falsche Schlüssel erhalten 401, und ein Schlüssel, der nur auf bestimmte Operationen beschränkt ist, erhält bei den übrigen 403. Der /health-Endpunkt ist stets ausgenommen. Ist kein API-Schlüssel gesetzt, läuft der Server ohne Authentifizierung und akzeptiert alle Anfragen. Das ist nur in einem vertrauenswürdigen lokalen Netzwerk angebracht.
Schnellstart
Bringen Sie die lokale API mit Docker zum Laufen. Der erste Download umfasst etwa 3,8 GB.
Ihren API-Schlüssel holen
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"Ihren API-Schlüssel finden Sie im API-Schlüssel-Dashboard.
Den Server starten
docker run -d --name promptshield \
-e PROMPTSHIELD_API_KEY="$PROMPTSHIELD_API_KEY" \
-p 8000:8000 \
-v promptshield-data:/data \
promptshield/promptshield-api:latestDas Image enthält Tesseract OCR, LibreOffice und die Erkennungsmodelle für Englisch und Französisch. Weitere Sprachen installieren Sie mit promptshield models install.
Prüfen, ob er läuft
curl http://localhost:8000/health
# → {"status": "ok", "version": "1.3.6"}Ihr erstes Dokument verarbeiten
AUTH="Authorization: Bearer ps_live_your_key_here"
curl -X POST http://localhost:8000/api/documents/upload \
-H "$AUTH" \
-F "file=@contract.pdf"
# → {"doc_id": "abc123", "filename": "contract.pdf", "page_count": 5, "status": "EXTRACTED"}
curl -X POST http://localhost:8000/api/documents/abc123/detect \
-H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"confidence_threshold": 0.7}'
# → {"doc_id": "abc123", "total_regions": 42, "regions": [...]}
curl -X POST http://localhost:8000/api/documents/abc123/anonymize \
-H "$AUTH"
# → {"doc_id": "abc123", "tokens_created": 42, "regions_removed": 0, "output_path": "..."}
curl -o contract-safe.pdf \
-H "$AUTH" \
http://localhost:8000/api/documents/abc123/download/pdfLieber eine lokale Python-Installation?
Das Python-Paket ist noch nicht auf PyPI, daher schlägt pip install promptshield-app fehl. Nutzen Sie das Docker-Image oben oder bauen Sie aus dem Quellcode. Wir aktualisieren diese Seite, sobald das Paket veröffentlicht ist.
Schritt-für-Schritt-Anleitung
Eine umfassende Anleitung, um die lokale API einzurichten und in Ihren Workflow einzubinden.
1. Voraussetzungen
Stellen Sie zunächst sicher, dass Folgendes installiert ist:
Optional (für volle Formatunterstützung):
2. Das SDK installieren
Installieren Sie das promptShield-Python-Paket. Die Basisinstallation verarbeitet PDF-Dateien. Fügen Sie das office-Extra für Word/Excel/PowerPoint hinzu.
Das Python-Paket ist noch nicht auf PyPI veröffentlicht, daher schlagen die beiden Befehle unten fehl. Nutzen Sie vorläufig das Docker-Image in Abschnitt 5. Alles andere auf dieser Seite gilt für beide Wege.
pip install promptshield-apppip install "promptshield-app[office]"Installieren Sie Sprachmodelle (Entitätspakete) über die CLI:
# Set the install directory (add to your shell profile)
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
# English pack — required (medium is recommended)
promptshield models install spacy-en-md
# For maximum accuracy (larger download)
promptshield models install spacy-en-lgInstallieren Sie zusätzliche Sprachpakete auf dieselbe Weise:
promptshield models install spacy-fr-md # French
promptshield models install spacy-de-md # German
promptshield models install spacy-es-md # Spanish
promptshield models install spacy-it-md # Italian
promptshield models install spacy-nl-md # Dutch
promptshield models install spacy-pt-md # Portuguese3. Authentifizierung
Die lokale API verwendet Ihren promptShield-API-Schlüssel zur Lizenzprüfung. Setzen Sie ihn als Umgebungsvariable oder übergeben Sie ihn beim Start des Servers.
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"$env:PROMPTSHIELD_API_KEY = "ps_live_your_key_here"Der API-Schlüssel wird beim Start online geprüft und danach alle 6 Stunden erneut. Jede Antwort wird lokal zwischengespeichert, sodass der Server bis zu 3 Tage weiterläuft, wenn er den Lizenzserver nicht erreicht.
4. Den API-Server starten
Starten Sie den lokalen Server mit einem einzigen Befehl:
promptshield serve
# Starting PromptShield API server on 127.0.0.1:8000
# Health: http://127.0.0.1:8000/health (no auth)
# Schema: http://127.0.0.1:8000/openapi.json (send: Authorization: Bearer <your-api-key>)
# /docs and /redoc are served but require that same header, so a browser cannot open them directly.Verfügbare Optionen:
| --host | Bindeadresse (Standard: 127.0.0.1) |
| --port | Bindeport (Standard: 8000) |
| --api-key | API-Schlüssel (Alternative zur Umgebungsvariable) |
Nach dem Start ist die API unter der angezeigten URL erreichbar. Das OpenAPI-Schema finden Sie unter /openapi.json; senden Sie auch bei dieser Anfrage Ihren API-Schlüssel mit.
5. Docker-Bereitstellung
Für den Produktivbetrieb: Mit Docker entfällt die Installation, denn alle Abhängigkeiten sind im Image gebündelt.
docker run -d --name promptshield \
-e PROMPTSHIELD_API_KEY="ps_live_your_key_here" \
-p 8000:8000 \
-v promptshield-data:/data \
promptshield/promptshield-api:latest# docker-compose.yml
services:
promptshield:
image: promptshield/promptshield-api:latest
ports:
- "8000:8000"
volumes:
- promptshield-data:/data
environment:
- PROMPTSHIELD_API_KEY=${PROMPTSHIELD_API_KEY}
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
volumes:
promptshield-data:Erstellen Sie eine .env-Datei mit Ihrem API-Schlüssel:
PROMPTSHIELD_API_KEY=ps_live_your_key_hereDas Docker-Image enthält:
6. API-Workflow
Der Standard-Workflow zur Dokumentverarbeitung hat 5 Schritte:
Vollständiges Workflow-Beispiel (cURL)
# 1. Upload
AUTH="Authorization: Bearer ps_live_your_key_here"
DOC_ID=$(curl -s -X POST http://localhost:8000/api/documents/upload \
-H "$AUTH" \
-F "file=@contract.pdf" | python -c "import sys,json; print(json.load(sys.stdin)['doc_id'])")
echo "Document ID: $DOC_ID"
# 2. Detect PII (with optional inline overrides)
curl -X POST http://localhost:8000/api/documents/$DOC_ID/detect \
-H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"confidence_threshold": 0.7, "regex_enabled": true, "ner_enabled": true}'
# → {"doc_id": "...", "total_regions": 42, "regions": [...]}
# 3. Review detected regions
curl -H "$AUTH" http://localhost:8000/api/documents/$DOC_ID/regions | python -m json.tool
# → [{"id": "...", "pii_type": "PERSON", "text": "John Smith", "confidence": 0.98,
# "action": "TOKENIZE", ...}, ...]
# 3b. Bulk-update region actions before anonymizing (region_ids from step 3)
curl -X PUT http://localhost:8000/api/documents/$DOC_ID/regions/batch-action \
-H "$AUTH" \
-H "Content-Type: application/json" \
-d '{"region_ids": ["<id1>", "<id2>"], "action": "REMOVE"}'
# 4. Anonymize
curl -X POST http://localhost:8000/api/documents/$DOC_ID/anonymize \
-H "$AUTH"
# → {"doc_id": "...", "tokens_created": 42, "regions_removed": 0}
# 5. Download the anonymized document
curl -o contract-safe.pdf \
-H "$AUTH" \
http://localhost:8000/api/documents/$DOC_ID/download/pdf
echo "Done! Anonymized file saved to contract-safe.pdf"7. CLI-Befehle
Verarbeiten Sie Dokumente direkt über die Kommandozeile, ohne einen Server zu starten:
promptshield detect invoice.pdf
# Detected 23 PII entities across 5 pages
promptshield detect invoice.pdf -o report.json
# Report saved to report.json
# Tune the pipeline per run — every desktop-app setting is also a CLI flag.
promptshield detect contract.pdf \
--language en --countries US \
--ner-backend Davlan/bert-base-multilingual-cased-ner-hrl \
--no-llm --fuzziness 0.5 \
--ner-types PERSON,ORG \
-e SA-2026-0847 -e "84-329-1057" \
--export-review -o contract.psreview
# Or load all of the above from demo/setup.json by locale:
promptshield detect contract.pdf --preset en --export-review -o contract.psreviewpromptshield anonymize contract.pdf -o contract-safe.pdf
# Anonymized: 42 tokens created, saved to contract-safe.pdf
# Permanently redact PII (black boxes, irreversible)
promptshield anonymize contract.pdf --redact -o contract-redacted.pdfpromptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdfAlle CLI-Befehle prüfen Ihren API-Schlüssel und verarbeiten Dokumente lokal. Keine Dokumentdaten verlassen Ihr Gerät.
Modell-Add-ons
Mit dem integrierten models-Befehl durchsuchen, installieren und entfernen Sie Sprachpakete für die Entitätserkennung. Setzen Sie PROMPTSHIELD_ASSETS_DIR, damit sowohl die CLI als auch der laufende Server sie finden.
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"promptshield models list
# Language packs (NER)
# [ ] spacy-en-sm English (small) (12 MB)
# [installed] spacy-en-md English (medium) (33 MB)
# [ ] spacy-fr-md French (medium) (16 MB) ...promptshield models install spacy-fr-md
# Installing spacy-fr-md (French (medium))...
# Downloading... 16.0/16.0 MB (100%)
# Verifying integrity...
# Extracting...
# Installed to ~/.local/share/promptshield/assets/spacy/fr_core_news_mdpromptshield models installed
# Installed models:
# spacy-en-md English (medium)
# spacy-fr-md French (medium)promptshield models remove spacy-fr-mdInstallierte Pakete werden von detect, anonymize und dem laufenden API-Server automatisch erkannt. Der install-Befehl kommuniziert direkt mit dem Lizenzserver, ein laufender Sidecar ist nicht nötig.
8. Eigene Ausdrücke
Die integrierten Regex-Muster und die Entitätserkennung decken die meisten PII ab, doch jede Organisation hat eigene Kennungen: Vertragsnummern, interne Projektcodes, Steuernummern, Vertraulichkeitsvermerke. Fügen Sie sie als Ausdrücke hinzu, dann werden sie wie jede andere PII behandelt: als Typ CUSTOM markiert, mit vollständiger bbox und Propagierung über die Seiten hinweg. Verfügbar über die CLI (-e / --expression), die selbst gehostete HTTP-API (blacklist_terms) und Voreinstellungen in demo/setup.json.
# Literal text — case-insensitive substring match
promptshield detect contract.pdf -e SA-2026-0847 -e "84-329-1057"
# Repeatable — pass as many -e flags as you need
promptshield detect contract.pdf \
-e ACME-CONFIDENTIAL \
-e "Internal Use Only" \
-e CUST-12345
# Regex — prefix with "re:" for full regex semantics
promptshield detect contract.pdf \
-e "re:CASE-\d{4}-[A-Z]{3}" \
-e "re:Project [A-Z][a-z]+"# Same feature on the self-hosted HTTP API.
curl -X POST http://localhost:8000/api/documents/$DOC_ID/detect \
-H "$AUTH" \
-H "Content-Type: application/json" \
-d '{
"expressions": ["SA-2026-0847", "84-329-1057"],
"expressions_action": "tokenize",
"expressions_fuzziness": 1.0
}'
# expressions_action: "none" | "tokenize" | "remove"
# expressions_fuzziness: 1.0 = exact match, 0.5 = fuzzy edit-distance match
#
# Back-compat: the legacy keys "blacklist_terms" / "blacklist_action" /
# "blacklist_fuzziness" still work and map to the same fields via
# Pydantic alias — existing integrations don't need changes.# demo/setup.json
{
"en": {
"language": "en",
"countries": ["US"],
"ner_backend": "Davlan/bert-base-multilingual-cased-ner-hrl",
"expressions": ["SA-2026-0847", "84-329-1057"],
"fuzziness": 0.5
}
}
# Then any time:
promptshield detect contract.pdf --preset en --export-review -o contract.psreviewZur Benennung: expressions ist nun der kanonische Name auf allen drei Oberflächen: CLI (-e / --expression), HTTP-API (expressions / expressions_action / expressions_fuzziness) und Beschriftung in der Desktop-Oberfläche. Die früheren Schlüssel blacklist_terms / blacklist_action / blacklist_fuzziness der HTTP-API funktionieren zur Abwärtskompatibilität weiterhin über einen Pydantic-Alias, sodass bestehende Integrationen weiterlaufen.
Prüf-Workflow: API → Desktop
Automatisierte Erkennung in großem Umfang ist erst die eine Hälfte. Keine automatische Erkennung erreicht 100 % Präzision: Es gibt immer Fehltreffer zu verwerfen und übersehene Entitäten zu ergänzen. Für die andere Hälfte hat promptShield ein portables .psreview-Bündel: per Programm erkennen, zur visuellen Prüfung durch einen Menschen in die Desktop-App importieren, dann anonymisieren.
Schritt 1a: Erkennen und exportieren (CLI, in einem Durchgang)
# Detect + bundle in one command
promptshield detect contract.pdf --export-review -o contract.psreview
# Ingesting contract.pdf...
# Detecting PII on page 1/3...
# Detecting PII on page 2/3...
# Detecting PII on page 3/3...
# Detected 14 PII region(s) across 3 page(s) in 1240ms.
# Review bundle saved to contract.psreview (14 region(s))Schritt 1b: Erkennen und exportieren (HTTP-API)
# 1. Upload document
curl -X POST http://localhost:8000/api/documents/upload \
-H "Authorization: Bearer $PROMPTSHIELD_API_KEY" \
-F "file=@contract.pdf"
# → {"doc_id": "abc123ef", "page_count": 3, ...}
# 2. Run detection
curl -X POST http://localhost:8000/api/documents/abc123ef/detect \
-H "Authorization: Bearer $PROMPTSHIELD_API_KEY"
# 3. Download the review bundle
curl http://localhost:8000/api/documents/abc123ef/export-review \
-H "Authorization: Bearer $PROMPTSHIELD_API_KEY" \
-o contract.psreview.psreview API
/api/documents/{id}/export-reviewPrüfbündel exportieren
Laden Sie das Dokument und alle seine Regionen-Anmerkungen als portables .psreview-ZIP-Bündel herunter.
/api/documents/import-reviewPrüfbündel importieren
Laden Sie ein .psreview-Bündel hoch. Der Endpunkt extrahiert das Dokument (mit OCR), übernimmt die gespeicherten Regionen-Anmerkungen und öffnet das Dokument im Status REVIEWING, bereit zur visuellen Qualitätsprüfung, ohne die Erkennung erneut auszuführen.
Schritt 2: Prüfen, bearbeiten und anonymisieren
Verwerfen Sie Fehltreffer in der Regionen-Seitenleiste (Aktion auf Abbrechen setzen), zeichnen Sie neue Regionen für alles ein, was das Modell übersehen hat, und klicken Sie dann auf Herunterladen. Die Desktop-App anonymisiert das Dokument und speichert das geschwärzte PDF in Ihrem Downloads-Ordner.
8. Python-SDK (direkter Import)
Für fortgeschrittene Integrationen importieren Sie die Kernmodule direkt in Ihren Python-Code. Das gibt Ihnen die volle Kontrolle über jeden Verarbeitungsschritt.
from promptshield import PromptShield
ps = PromptShield()
def process(input_path: str, output_path: str):
# Step 1 — Detect PII (runs the full local pipeline)
result = ps.detect(input_path)
print(f"Loaded: {result.file} ({result.pages} pages)")
print(f"Total PII entities: {result.total_regions}")
for page in result.regions:
for entity in page["entities"]:
print(f" Page {page['page']}: [{entity['type']}] {entity['text']}")
# Step 2 — Anonymize (reversible tokens by default; pass redact=True
# for permanent removal). Output is always a PDF.
out = ps.anonymize(input_path, output_path)
print(f"Anonymized: {out.tokens_created} tokens, saved to {out.output_file}")
# Step 3 — Restore the originals later from the local token vault
restored = ps.detokenize(output_path, "contract-restored.pdf")
print(f"Restored {restored.tokens_replaced} tokens")
process("contract.pdf", "contract-safe.pdf")
# Async variants are available too: ps.adetect / ps.aanonymize / ps.adetokenizeBeispiel für Stapelverarbeitung
Mehrere Dateien in einem Verzeichnis verarbeiten:
from pathlib import Path
from promptshield import PromptShield
ps = PromptShield()
def batch_process(input_dir: str, output_dir: str):
input_path = Path(input_dir)
output_path = Path(output_dir)
output_path.mkdir(parents=True, exist_ok=True)
files = list(input_path.glob("*.pdf"))
print(f"Processing {len(files)} files...")
for i, file in enumerate(files, 1):
print(f"[{i}/{len(files)}] {file.name}")
out_file = output_path / f"anon_{file.stem}.pdf"
result = ps.anonymize(str(file), str(out_file))
print(f" → {result.tokens_created} tokens, saved to {out_file.name}")
print("Batch complete!")
batch_process("./documents", "./anonymized")9. Sicherheit & Datenschutz
promptShield ist für Zero-Trust-Umgebungen konzipiert:
10. Fehlerbehebung
Häufige Probleme und Lösungen:
Fehler 'No spaCy model found' oder 'no NER model loaded'
Setzen Sie PROMPTSHIELD_ASSETS_DIR und installieren Sie ein Paket: promptshield models install spacy-en-md. Alternativ für eine systemweite Installation: python -m spacy download en_core_web_sm
OCR funktioniert bei gescannten PDFs nicht
Installieren Sie Tesseract OCR und stellen Sie sicher, dass es in Ihrem PATH liegt. Unter Windows fügt der Installer es automatisch hinzu.
Office-Dateien lassen sich nicht konvertieren
Word-, Excel- und PowerPoint-Dateien (.docx, .xlsx, .xls, .pptx) werden in Python konvertiert, ohne LibreOffice. Prüfen Sie, ob das office-Extra installiert ist und die Datei nicht passwortgeschützt ist.
'Invalid API key' beim Start
Stellen Sie sicher, dass Ihr Schlüssel mit ps_live_ beginnt und dass Ihr Abonnement aktiv ist. Schlüssel lassen sich unter /developers/api-keys verwalten.
Dokumente
/api/documents/uploadDokument hochladen
Laden Sie ein Dokument zur Verarbeitung hoch. Unterstützt PDF-, DOCX-, XLSX-, PPTX- und Bilddateien.
/api/documentsDokumente auflisten
Rufen Sie alle hochgeladenen Dokumente mit ihrem Erkennungs- und Anonymisierungsstatus ab.
/api/documents/{id}Dokument abrufen
Rufen Sie detaillierte Informationen zu einem bestimmten Dokument ab, einschließlich Seitenzahl und Erkennungsstatus.
/api/documents/{id}Dokument löschen
Entfernen Sie ein Dokument und alle zugehörigen Daten vom Server.
Erkennung
/api/documents/{id}/detectPII erkennen
Führen Sie die PII-Erkennungspipeline für ein Dokument aus. Akzeptiert einen optionalen JSON-Body, um die Erkennungseinstellungen (confidence_threshold, regex_enabled, ner_enabled, regex_types usw.) nur für diesen Durchlauf zu überschreiben.
/api/documents/{id}/redetectPII erneut erkennen
Führen Sie die Erkennung mit voller Parameterkontrolle erneut aus. Akzeptiert confidence_threshold, regex_types, ner_types, blacklist_terms und mehr.
/api/documents/{id}/detection-progressErkennungsfortschritt
Rufen Sie den Fortschritt eines laufenden Erkennungsauftrags ab (Prozentsatz, aktuelle Seite und Status).
/api/documents/{id}/regionsRegionen abrufen
Rufen Sie alle erkannten PII-Regionen eines Dokuments mit Typ, Text, Konfidenzwert und Begrenzungsrahmen ab.
/api/documents/{id}/regions/batch-actionRegionen im Stapel aktualisieren
Legen Sie die Aktion (TOKENIZE, REMOVE oder CANCEL) für mehrere Regionen auf einmal fest, gefiltert nach Entitätstyp.
Anonymisieren & Exportieren
/api/documents/{id}/regions/syncRegionen synchronisieren
Ersetzen Sie die Regionenliste eines Dokuments vollständig. Nutzen Sie dies nach dem clientseitigen Bearbeiten von Regionen, um Änderungen vor dem Anonymisieren zu übermitteln.
/api/documents/{id}/anonymizeDokument anonymisieren
Anonymisieren Sie ein Dokument, indem erkannte PII durch Codes ersetzt werden. Gibt das verarbeitete Dokument zurück.
/api/documents/{id}/download/{type}Anonymisierte Datei herunterladen
Laden Sie die anonymisierte Ausgabe herunter. {type} ist 'pdf' oder 'text'. Die Ausgabe wird stets als PDF gerendert (Nicht-PDF-Eingaben werden konvertiert), daher ist 'pdf' das primäre Format.
/api/documents/batch-anonymizeStapel-Anonymisierung
Anonymisieren Sie mehrere Dokumente in einer einzigen Anfrage: bis zu 50 pro Anfrage, jeweils 3 gleichzeitig verarbeitet.
Dekodieren
/api/detokenizeText dekodieren
Ersetzen Sie Codes in einem Text durch ihre ursprünglichen Werte aus dem Code-Register.
/api/detokenize/fileDatei dekodieren
Laden Sie ein kodiertes Dokument hoch und erhalten Sie eine Version, in der alle Codes wieder durch die ursprünglichen Werte ersetzt sind.
Code-Register
/api/vault/statusStatus des Code-Registers
Rufen Sie die Statistik des Code-Registers ab: Gesamtzahl der Codes, Gesamtzahl der Dokumente, Registergröße.
/api/vault/tokensCodes auflisten
Rufen Sie alle im Code-Register gespeicherten Zuordnungen von Code zu Originalwert ab.
/api/vault/exportCode-Register exportieren
Exportieren Sie das gesamte Code-Register als JSON-Datei zur Sicherung oder Migration.
/api/vault/importCode-Register importieren
Importieren Sie ein zuvor als JSON exportiertes Code-Register, um Code-Zuordnungen wiederherzustellen.
Health
/healthHealth-Check
Gibt den Status des Servers zurück. Geeignet für Monitoring und die Health-Probes von Load Balancern.
Einstellungen
/api/settingsEinstellungen abrufen
Rufen Sie die aktuelle Erkennungs- und Verarbeitungskonfiguration ab (Schwellenwerte, aktivierte Pipelines, Sprache usw.).
/api/settingsEinstellungen aktualisieren
Aktualisieren Sie die globalen Erkennungseinstellungen teilweise. Änderungen gelten für alle nachfolgenden Erkennungsdurchläufe.
/api/settings/patternsEigene Muster auflisten
Rufen Sie alle eigenen Regex-Muster für die PII-Erkennung ab.
/api/settings/patternsEigenes Muster erstellen
Fügen Sie ein neues eigenes Regex-Muster für die PII-Erkennung hinzu. Muster werden zusammen mit den integrierten Regeln ausgewertet.
Beispiel
# 1. Upload a document
curl -X POST http://localhost:8000/api/documents/upload \
-F "file=@contract.pdf"
# → {"doc_id": "abc123", "filename": "contract.pdf", "page_count": 5, "status": "EXTRACTED"}
# 2. Run PII detection
curl -X POST http://localhost:8000/api/documents/abc123/detect
# → {"doc_id": "abc123", "total_regions": 42, "regions": [...]}
# 3. Get detected regions
curl http://localhost:8000/api/documents/abc123/regions
# → [{"id": "...", "pii_type": "PERSON", "text": "John Smith", "confidence": 0.98,
# "page_number": 1, "bbox": {...}, "source": "NER", "action": "TOKENIZE"}, ...]
# 4. Anonymize the document
curl -X POST http://localhost:8000/api/documents/abc123/anonymize
# → {"doc_id": "abc123", "tokens_created": 42, "regions_removed": 0}
# 5. Download anonymized PDF
curl -o contract-safe.pdf \
http://localhost:8000/api/documents/abc123/download/pdfPython-SDK
Die PromptShield-Klasse führt die gesamte Pipeline lokal aus: erkennen, anonymisieren und dekodieren in drei Aufrufen. Die gesamte Verarbeitung läuft auf Ihrem Gerät; keine Dokumentdaten verlassen es.
Das SDK gehört zum Python-Paket, das noch nicht auf PyPI ist. Bis dahin leisten die HTTP-Endpunkte oben dasselbe.
from promptshield import PromptShield
ps = PromptShield()
# PII erkennen
result = ps.detect("contract.pdf")
print(f"{result.total_regions} entities across {result.pages} pages")
for page in result.regions:
for entity in page["entities"]:
print(f" [{entity['type']}] {entity['text']}")
# Anonymisieren (umkehrbare Kodierung)
out = ps.anonymize("contract.pdf", "contract-safe.pdf")
print(f"Done: {out.tokens_created} tokens created")
# Die ursprünglichen Werte wiederherstellen
restored = ps.detokenize("contract-safe.pdf", "contract-restored.pdf")
print(f"Restored {restored.tokens_replaced} tokens")Fehlerbehandlung
Alle Fehlerantworten folgen einem Standard-JSON-Format mit einem detail-Feld, das den Fehler beschreibt.
Ungültige Anfrage. Falsche Parameter oder eine beschädigte oder nicht unterstützte Datei.
Nicht autorisiert. Fehlender oder ungültiger API-Schlüssel (Authorization: Bearer) im API-Schlüssel-Modus.
Verboten. Dem API-Schlüssel fehlt der erforderliche Scope (detect / anonymize / detokenize).
Nicht gefunden. Die Dokument-ID existiert nicht.
Nicht verarbeitbar. Ein erforderliches Feld fehlt, oder die Datei ist passwortgeschützt.
Serverfehler. Prüfen Sie die Serverprotokolle auf Details.
Ein erforderliches Erkennungsmodell ist nicht installiert. Installieren Sie es mit promptshield models install.
{
"detail": "Document not found: abc123"
}Ratenbegrenzungen
Die selbst gehostete API akzeptiert standardmäßig bis zu 6.000 Anfragen pro Minute und Client-IP. Mit der Umgebungsvariablen PROMPTSHIELD_SELF_HOSTED_RATE ändern Sie dieses Limit.