Developers
API-Referenz

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:8000

Ersetzen 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:

bash
curl -H "Authorization: Bearer $PROMPTSHIELD_API_KEY" \
  http://localhost:8000/openapi.json -o promptshield-openapi.json

Ein 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.

1

Ihren API-Schlüssel holen

bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

Ihren API-Schlüssel finden Sie im API-Schlüssel-Dashboard.

2

Den Server starten

bash
docker run -d --name promptshield \
  -e PROMPTSHIELD_API_KEY="$PROMPTSHIELD_API_KEY" \
  -p 8000:8000 \
  -v promptshield-data:/data \
  promptshield/promptshield-api:latest

Das Image enthält Tesseract OCR, LibreOffice und die Erkennungsmodelle für Englisch und Französisch. Weitere Sprachen installieren Sie mit promptshield models install.

3

Prüfen, ob er läuft

bash
curl http://localhost:8000/health
# → {"status": "ok", "version": "1.3.6"}
4

Ihr erstes Dokument verarbeiten

bash
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/pdf

Lieber 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:

Docker (die derzeit unterstützte Installation)
Python 3.11 oder neuer
pip (in Python enthalten)
Ein promptShield-API-Schlüssel (Pro-Plan)

Optional (für volle Formatunterstützung):

Tesseract OCR: für gescannte/bildbasierte PDFs
LibreOffice: nicht nötig für .docx, .xlsx, .xls und .pptx, die in Python konvertiert werden

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.

Basisinstallation (nur PDF)
bash
pip install promptshield-app
Mit Office-Formatunterstützung
bash
pip install "promptshield-app[office]"

Installieren Sie Sprachmodelle (Entitätspakete) über die CLI:

bash
# 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-lg

Installieren Sie zusätzliche Sprachpakete auf dieselbe Weise:

bash
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   # Portuguese

3. 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.

macOS / Linux
bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"
Windows (PowerShell)
bash
$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:

bash
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:

--hostBindeadresse (Standard: 127.0.0.1)
--portBindeport (Standard: 8000)
--api-keyAPI-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.

Einzelner Container
bash
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
Mit Docker Compose
bash
# 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:

.env
bash
PROMPTSHIELD_API_KEY=ps_live_your_key_here

Das Docker-Image enthält:

Tesseract OCR mit 8 Sprachpaketen (EN, FR, DE, ES, IT, NL, PT, PL)
LibreOffice für die Konvertierung von Office-Formaten
spaCy-Modelle für Englisch und Französisch vorinstalliert (weitere Sprachen über models install)
Nicht-Root-Nutzer, Health-Checks, persistentes Datenvolumen

6. API-Workflow

Der Standard-Workflow zur Dokumentverarbeitung hat 5 Schritte:

1Upload: Senden Sie Ihr Dokument an den Server
2Erkennung: Führen Sie die PII-Erkennungspipeline aus (Regex, Entitätserkennung und optional ein LLM)
3Prüfung: Sehen Sie die erkannten Regionen durch, bearbeiten oder bestätigen Sie sie
4Anonymisierung: Ersetzen Sie PII durch Codes
5Download: Rufen Sie das anonymisierte Dokument ab

Vollständiges Workflow-Beispiel (cURL)

cURL
bash
# 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:

PII erkennen und einen JSON-Bericht speichern
bash
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.psreview
Ein Dokument in einem Schritt anonymisieren
bash
promptshield 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.pdf
In einem zuvor anonymisierten Dokument die Codes durch die Originalwerte ersetzen
bash
promptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdf

Alle 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.

Legen Sie das Installationsverzeichnis einmal fest (fügen Sie es Ihrem Shell-Profil hinzu):
bash
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
Verfügbare Pakete mit Installationsstatus durchsuchen
bash
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)  ...
Ein Paket herunterladen und installieren (kein Server erforderlich)
bash
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_md
In PROMPTSHIELD_ASSETS_DIR installierte Pakete auflisten
bash
promptshield models installed
# Installed models:
#   spacy-en-md   English (medium)
#   spacy-fr-md   French (medium)
Ein Paket entfernen
bash
promptshield models remove spacy-fr-md

Installierte 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.

CLI: wiederholbares Flag -e / --expression
bash
# 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]+"
HTTP-API: Body von POST /api/documents/{id}/detect
bash
# 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.
Voreinstellungsdatei: bei jedem --preset <locale>-Aufruf angewendet
bash
# 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.psreview

Zur 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.

📂
Stapel-Erkennung
API oder CLI
📦
.psreview-Bündel
Dokument + Anmerkungen
🖥️
Desktop-Prüfung
Fehltreffer verwerfen · übersehene PII ergänzen
✅
Anonymisierte PDFs

Schritt 1a: Erkennen und exportieren (CLI, in einem Durchgang)

bash
# 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)

bash
# 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

GET
/api/documents/{id}/export-review

Prüfbündel exportieren

Laden Sie das Dokument und alle seine Regionen-Anmerkungen als portables .psreview-ZIP-Bündel herunter.

POST
/api/documents/import-review

Prü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.

Vollständiges Python-Beispiel
bash
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.adetokenize

Beispiel für Stapelverarbeitung

Mehrere Dateien in einem Verzeichnis verarbeiten:

batch_process.py
bash
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:

Die gesamte Verarbeitung läuft lokal: Dokumentinhalte werden niemals an externe Server gesendet
Das Code-Register bleibt auf Ihrem Gerät, innerhalb derselben Vertrauensgrenze wie Ihre Quelldokumente, und wird niemals hochgeladen
Die Authentifizierung per API-Schlüssel verhindert unbefugten Zugriff im selbst gehosteten Modus
Docker läuft als Nicht-Root-Nutzer mit minimalen Rechten
Der API-Schlüssel wird beim Start und alle 6 Stunden online geprüft und lokal zwischengespeichert (höchstens 3 Tage offline)

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

POST
/api/documents/upload

Dokument hochladen

Laden Sie ein Dokument zur Verarbeitung hoch. Unterstützt PDF-, DOCX-, XLSX-, PPTX- und Bilddateien.

GET
/api/documents

Dokumente auflisten

Rufen Sie alle hochgeladenen Dokumente mit ihrem Erkennungs- und Anonymisierungsstatus ab.

GET
/api/documents/{id}

Dokument abrufen

Rufen Sie detaillierte Informationen zu einem bestimmten Dokument ab, einschließlich Seitenzahl und Erkennungsstatus.

DELETE
/api/documents/{id}

Dokument löschen

Entfernen Sie ein Dokument und alle zugehörigen Daten vom Server.

Erkennung

POST
/api/documents/{id}/detect

PII 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.

POST
/api/documents/{id}/redetect

PII erneut erkennen

Führen Sie die Erkennung mit voller Parameterkontrolle erneut aus. Akzeptiert confidence_threshold, regex_types, ner_types, blacklist_terms und mehr.

GET
/api/documents/{id}/detection-progress

Erkennungsfortschritt

Rufen Sie den Fortschritt eines laufenden Erkennungsauftrags ab (Prozentsatz, aktuelle Seite und Status).

GET
/api/documents/{id}/regions

Regionen abrufen

Rufen Sie alle erkannten PII-Regionen eines Dokuments mit Typ, Text, Konfidenzwert und Begrenzungsrahmen ab.

PUT
/api/documents/{id}/regions/batch-action

Regionen im Stapel aktualisieren

Legen Sie die Aktion (TOKENIZE, REMOVE oder CANCEL) für mehrere Regionen auf einmal fest, gefiltert nach Entitätstyp.

Anonymisieren & Exportieren

PUT
/api/documents/{id}/regions/sync

Regionen 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.

POST
/api/documents/{id}/anonymize

Dokument anonymisieren

Anonymisieren Sie ein Dokument, indem erkannte PII durch Codes ersetzt werden. Gibt das verarbeitete Dokument zurück.

GET
/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.

POST
/api/documents/batch-anonymize

Stapel-Anonymisierung

Anonymisieren Sie mehrere Dokumente in einer einzigen Anfrage: bis zu 50 pro Anfrage, jeweils 3 gleichzeitig verarbeitet.

Dekodieren

POST
/api/detokenize

Text dekodieren

Ersetzen Sie Codes in einem Text durch ihre ursprünglichen Werte aus dem Code-Register.

POST
/api/detokenize/file

Datei 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

GET
/api/vault/status

Status des Code-Registers

Rufen Sie die Statistik des Code-Registers ab: Gesamtzahl der Codes, Gesamtzahl der Dokumente, Registergröße.

GET
/api/vault/tokens

Codes auflisten

Rufen Sie alle im Code-Register gespeicherten Zuordnungen von Code zu Originalwert ab.

POST
/api/vault/export

Code-Register exportieren

Exportieren Sie das gesamte Code-Register als JSON-Datei zur Sicherung oder Migration.

POST
/api/vault/import

Code-Register importieren

Importieren Sie ein zuvor als JSON exportiertes Code-Register, um Code-Zuordnungen wiederherzustellen.

Health

GET
/health

Health-Check

Gibt den Status des Servers zurück. Geeignet für Monitoring und die Health-Probes von Load Balancern.

Einstellungen

GET
/api/settings

Einstellungen abrufen

Rufen Sie die aktuelle Erkennungs- und Verarbeitungskonfiguration ab (Schwellenwerte, aktivierte Pipelines, Sprache usw.).

PATCH
/api/settings

Einstellungen aktualisieren

Aktualisieren Sie die globalen Erkennungseinstellungen teilweise. Änderungen gelten für alle nachfolgenden Erkennungsdurchläufe.

GET
/api/settings/patterns

Eigene Muster auflisten

Rufen Sie alle eigenen Regex-Muster für die PII-Erkennung ab.

POST
/api/settings/patterns

Eigenes 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

cURL — Upload, Detect, Anonymize
bash
# 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/pdf

Python-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.

Python SDK
bash
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.

400

Ungültige Anfrage. Falsche Parameter oder eine beschädigte oder nicht unterstützte Datei.

401

Nicht autorisiert. Fehlender oder ungültiger API-Schlüssel (Authorization: Bearer) im API-Schlüssel-Modus.

403

Verboten. Dem API-Schlüssel fehlt der erforderliche Scope (detect / anonymize / detokenize).

404

Nicht gefunden. Die Dokument-ID existiert nicht.

422

Nicht verarbeitbar. Ein erforderliches Feld fehlt, oder die Datei ist passwortgeschützt.

500

Serverfehler. Prüfen Sie die Serverprotokolle auf Details.

503

Ein erforderliches Erkennungsmodell ist nicht installiert. Installieren Sie es mit promptshield models install.

Error Response Format
bash
{
  "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.