Developers
API-referentie

Documentatie van de API

Volledige REST-API-referentie voor de zelfgehoste promptShield-engine. Alle endpoints zijn beschikbaar op de URL van uw installatie.

Basis-URL

http://localhost:8000

Vervang door de host en poort van uw installatie.

OpenAPI-schema

De server biedt /docs (Swagger UI), /redoc en /openapi.json aan. In API-sleutelmodus vereisen alle drie de Authorization-header, dus een browser kan ze niet rechtstreeks openen. Haal het schema op en laad het in een client die een header kan meesturen:

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

Een browser kan de Authorization-header niet meesturen bij een navigatie, dus /docs antwoordt met 401 in API-sleutelmodus. Het schema hierboven is de bruikbare route.

Authenticatie

Wanneer PROMPTSHIELD_API_KEY is ingesteld (via promptshield serve --api-key of de Docker-omgevingsvariabele), moet elke aanvraag die meesturen als Authorization: Bearer <api-key>; ontbrekende of verkeerde sleutels krijgen 401, en een sleutel die tot bepaalde bewerkingen is beperkt, krijgt 403 op de rest. Het endpoint /health is altijd vrijgesteld. Als er geen API-sleutel is ingesteld, draait de server zonder authenticatie en accepteert hij alle aanvragen. Dat is alleen verantwoord op een vertrouwd lokaal netwerk.

Snel aan de slag

Start de lokale API met Docker. De eerste download is ongeveer 3,8 GB.

1

Uw API-sleutel ophalen

bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

Uw API-sleutel is beschikbaar in het dashboard voor API-sleutels.

2

De 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

De image bevat Tesseract OCR, LibreOffice en de detectiemodellen voor Engels en Frans. Andere talen installeert u met promptshield models install.

3

Controleren of hij draait

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

Uw eerste document verwerken

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

Liever een lokale Python-installatie?

Het Python-pakket staat nog niet op PyPI, dus pip install promptshield-app werkt niet. Gebruik de Docker-image hierboven of bouw vanaf de broncode. We werken deze pagina bij zodra het pakket is gepubliceerd.

Stapsgewijze handleiding

Zo stelt u de lokale API in en neemt u hem op in uw workflow, stap voor stap.

1. Vereisten

Zorg dat u het volgende hebt geïnstalleerd voordat u begint:

Docker (de installatie die nu ondersteund wordt)
Python 3.11 of nieuwer
pip (inbegrepen bij Python)
Een promptShield-API-sleutel (Pro-abonnement)

Optioneel (voor volledige formaatondersteuning):

Tesseract OCR: voor gescande PDF's en PDF's die uit afbeeldingen bestaan
LibreOffice: niet nodig voor .docx, .xlsx, .xls en .pptx, die in Python worden geconverteerd

2. De SDK installeren

Installeer het promptShield Python-pakket. De basisinstallatie verwerkt PDF-bestanden. Voeg de office-extra toe voor Word/Excel/PowerPoint.

Het Python-pakket is nog niet op PyPI gepubliceerd, dus de twee opdrachten hieronder werken niet. Gebruik voorlopig de Docker-image in sectie 5. Al het andere op deze pagina geldt voor beide.

Basisinstallatie (alleen PDF)
bash
pip install promptshield-app
Met ondersteuning voor Office-formaten
bash
pip install "promptshield-app[office]"

Installeer taalmodellen (entiteitenpakketten) via de 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

Installeer extra taalpakketten op dezelfde manier:

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

De lokale API gebruikt uw promptShield-API-sleutel voor licentievalidatie. Stel die in als omgevingsvariabele of geef die mee bij het starten van de server.

macOS / Linux
bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"
Windows (PowerShell)
bash
$env:PROMPTSHIELD_API_KEY = "ps_live_your_key_here"

De API-sleutel wordt bij het opstarten online gevalideerd en daarna elke 6 uur opnieuw. Elk antwoord wordt lokaal gecachet, zodat de server tot 3 dagen blijft draaien als hij de licentieserver niet bereikt.

4. De API-server starten

Start de lokale server met één enkele opdracht:

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.

Beschikbare opties:

--hostBind-adres (standaard: 127.0.0.1)
--portBind-poort (standaard: 8000)
--api-keyAPI-sleutel (alternatief voor de omgevingsvariabele)

Na het starten is de API beschikbaar op de getoonde URL. Het OpenAPI-schema staat op /openapi.json; stuur ook bij die aanvraag uw API-sleutel mee.

5. Installatie met Docker

In productieomgevingen hoeft u met Docker niets te installeren: alle afhankelijkheden zitten in de image.

Enkele 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
Met 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:

Maak een .env-bestand met uw API-sleutel:

.env
bash
PROMPTSHIELD_API_KEY=ps_live_your_key_here

De Docker-image bevat:

Tesseract OCR met 8 taalpakketten (EN, FR, DE, ES, IT, NL, PT, PL)
LibreOffice voor de conversie van Office-formaten
spaCy-modellen voor Engels en Frans voorgeïnstalleerd (andere talen via models install)
Non-root-gebruiker, statuscontroles, persistent gegevensvolume

6. API-workflow

De standaardworkflow voor documentverwerking heeft 5 stappen:

1Uploaden. Stuur uw document naar de server
2Detecteren. Voer de PII-detectiepipeline uit (regex + entiteiten + optioneel LLM)
3Beoordelen. Inspecteer gedetecteerde regio's, bewerk of bevestig
4Anonimiseren. Vervang PII door codes
5Downloaden. Haal het geanonimiseerde document op

Volledig workflowvoorbeeld (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-opdrachten

Verwerk documenten rechtstreeks vanaf de opdrachtregel zonder een server te starten:

Detecteer PII en sla een JSON-rapport op
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
Anonimiseer een document in één stap
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
Herstel codes in een eerder geanonimiseerd document
bash
promptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdf

Alle CLI-opdrachten valideren uw API-sleutel en verwerken documenten lokaal. Er verlaten geen documentgegevens uw apparaat.

Model-add-ons

Gebruik de ingebouwde opdracht models om entiteitenpakketten te bekijken, te installeren en te verwijderen. Stel PROMPTSHIELD_ASSETS_DIR in zodat zowel de CLI als de draaiende server ze vindt.

Stel de installatiemap eenmalig in (voeg dit toe aan uw shellprofiel):
bash
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
Beschikbare pakketten bekijken, met installatiestatus
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)  ...
Een pakket downloaden en installeren (geen server vereist)
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
De pakketten weergeven die in PROMPTSHIELD_ASSETS_DIR zijn geïnstalleerd
bash
promptshield models installed
# Installed models:
#   spacy-en-md   English (medium)
#   spacy-fr-md   French (medium)
Een pakket verwijderen
bash
promptshield models remove spacy-fr-md

Geïnstalleerde pakketten worden automatisch gebruikt door detect, anonymize en de draaiende API-server. De opdracht install communiceert rechtstreeks met de licentieserver en heeft geen draaiende sidecar nodig.

8. Eigen expressies

De ingebouwde regex en entiteiten dekken de meeste PII, maar elke organisatie heeft ook eigen identificatoren, zoals contractnummers, interne projectcodes, fiscale nummers en vertrouwelijkheidsmarkeringen. Voeg ze toe als expressies: ze worden dan als volwaardige PII behandeld, gemarkeerd als type CUSTOM, met volledige bbox en doorgegeven aan alle pagina's. Beschikbaar in de CLI (-e / --expression), in de zelfgehoste HTTP-API (blacklist_terms) en via presets in demo/setup.json.

CLI: herhaalbare -e / --expression-vlag
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 van 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.
Presetbestand: toegepast bij elke aanroep van --preset <locale>
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

Over de naamgeving: expressions is nu de canonieke naam in alle drie de interfaces: CLI (-e / --expression), HTTP-API (expressions / expressions_action / expressions_fuzziness) en het label in de desktopinterface. De eerdere sleutels blacklist_terms / blacklist_action / blacklist_fuzziness van de HTTP-API werken nog steeds via een Pydantic-alias voor achterwaartse compatibiliteit, zodat bestaande integraties blijven werken.

Beoordelingsworkflow: API → desktop

Automatische detectie op grote schaal is maar het halve werk. Ze haalt nooit 100% precisie: er blijven altijd valse positieven om af te wijzen en gemiste entiteiten om toe te voegen. Daarvoor heeft promptShield de draagbare .psreview-bundel: detecteer programmatisch, importeer in de desktop-app voor een visuele controle door een mens en anonimiseer daarna.

📂
Batchdetectie
API of CLI
📦
.psreview-bundel
document + annotaties
🖥️
Beoordeling op desktop
FP's afwijzen · gemiste PII toevoegen
✅
Geanonimiseerde PDF's

Stap 1a: detecteren en exporteren (CLI, in één keer)

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

Stap 1b: detecteren en exporteren (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

Beoordelingsbundel exporteren

Download het document en al zijn regio-annotaties als een draagbare .psreview-ZIP-bundel.

POST
/api/documents/import-review

Beoordelingsbundel importeren

Upload een .psreview-bundel. Het document wordt uitgepakt (met OCR), de opgeslagen regio-annotaties worden geïnjecteerd en het document opent in de status REVIEWING, klaar voor visuele QA zonder de detectie opnieuw uit te voeren.

Stap 2: beoordelen, bewerken en anonimiseren

Wijs valse positieven af in de zijbalk met regio's (zet de actie op Annuleren), teken nieuwe regio's voor alles wat het model heeft gemist en klik daarna op Downloaden. De desktop-app voert de anonimisering uit en slaat de geanonimiseerde PDF op in uw map Downloads.

8. Python-SDK (directe import)

Voor geavanceerde integraties importeert u de kernmodules rechtstreeks in uw Python-code. Dat geeft u volledige controle over elke verwerkingsstap.

Volledig Python-voorbeeld
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

Voorbeeld van batchverwerking

Meerdere bestanden in een map verwerken:

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. Beveiliging & gegevensprivacy

promptShield is ontworpen voor zero-trust-omgevingen:

Alle verwerking gebeurt lokaal: er wordt nooit documentinhoud naar externe servers gestuurd
Het coderegister blijft op uw apparaat, binnen dezelfde vertrouwensgrens als uw brondocumenten, en wordt nooit geüpload
API-sleutelauthenticatie voorkomt ongeoorloofde toegang in de zelfgehoste modus
Docker draait als non-root met minimale privileges
API-sleutel bij het opstarten en elke 6 uur online gevalideerd en lokaal gecachet (maximaal 3 dagen offline)

10. Probleemoplossing

Veelvoorkomende problemen en oplossingen:

Fout 'No spaCy model found' of 'no NER model loaded'

Stel PROMPTSHIELD_ASSETS_DIR in en installeer een pakket: promptshield models install spacy-en-md. Of voor een systeembrede installatie: python -m spacy download en_core_web_sm

OCR werkt niet op gescande PDF's

Installeer Tesseract OCR en zorg dat het in uw PATH staat. Op Windows voegt de installer het automatisch toe.

Office-bestanden converteren niet

Word-, Excel- en PowerPoint-bestanden (.docx, .xlsx, .xls, .pptx) worden in Python geconverteerd, zonder LibreOffice. Controleer of de office-extra is geïnstalleerd en of het bestand niet met een wachtwoord is beveiligd.

'Invalid API key' bij het opstarten

Controleer of uw sleutel begint met ps_live_ en of uw abonnement actief is. Sleutels kunnen worden beheerd via /developers/api-keys.

Documenten

POST
/api/documents/upload

Document uploaden

Upload een document voor verwerking. Ondersteunt PDF-, DOCX-, XLSX-, PPTX- en afbeeldingsbestanden.

GET
/api/documents

Documenten weergeven

Haal alle geüploade documenten op met hun detectie- en anonimiseringsstatus.

GET
/api/documents/{id}

Document ophalen

Haal gedetailleerde informatie over een specifiek document op, waaronder het aantal pagina's en de detectiestatus.

DELETE
/api/documents/{id}

Document verwijderen

Verwijder een document en alle bijbehorende gegevens van de server.

Detectie

POST
/api/documents/{id}/detect

PII detecteren

Voer de PII-detectiepipeline uit op een document. Accepteert een optionele JSON-body om detectie-instellingen (confidence_threshold, regex_enabled, ner_enabled, regex_types enz.) alleen voor deze run te overschrijven.

POST
/api/documents/{id}/redetect

PII opnieuw detecteren

Voer de detectie opnieuw uit met volledige parametercontrole. Accepteert confidence_threshold, regex_types, ner_types, blacklist_terms en meer.

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

Detectievoortgang

Haal de voortgang van een lopende detectietaak op (percentage, huidige pagina en status).

GET
/api/documents/{id}/regions

Regio's ophalen

Haal alle gedetecteerde PII-regio's van een document op, met type, tekst, betrouwbaarheidsscore en selectiekader.

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

Regio's in batch bijwerken

Stel de actie (TOKENIZE, REMOVE of CANCEL) voor meerdere regio's tegelijk in, gefilterd op entiteitstype.

Anonimiseren & exporteren

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

Regio's synchroniseren

Vervang de regiolijst van een document volledig. Gebruik dit nadat u regio's aan de clientzijde hebt bewerkt, om de wijzigingen op te slaan vóór het anonimiseren.

POST
/api/documents/{id}/anonymize

Document anonimiseren

Anonimiseer een document: gedetecteerde PII wordt vervangen door codes. Geeft het verwerkte document terug.

GET
/api/documents/{id}/download/{type}

Geanonimiseerd document downloaden

Download de geanonimiseerde uitvoer. {type} is 'pdf' of 'text'. De uitvoer wordt altijd als PDF weergegeven (niet-PDF-invoer wordt geconverteerd), dus 'pdf' is het primaire formaat.

POST
/api/documents/batch-anonymize

In batch anonimiseren

Anonimiseer meerdere documenten in één aanvraag: tot 50 per aanvraag, 3 tegelijk verwerkt.

Decoderen

POST
/api/detokenize

Tekst decoderen

Vervang codes in een tekstreeks door hun oorspronkelijke waarden uit het coderegister.

POST
/api/detokenize/file

Bestand decoderen

Upload een gecodeerd document en ontvang een versie waarin alle codes zijn vervangen door de oorspronkelijke waarden.

Coderegister

GET
/api/vault/status

Status van het coderegister

Haal statistieken van het coderegister op: totaal aantal codes, totaal aantal documenten, registergrootte.

GET
/api/vault/tokens

Lijst van codes

Haal alle code-naar-origineel-toewijzingen op die in het coderegister zijn opgeslagen.

POST
/api/vault/export

Coderegister exporteren

Exporteer het volledige coderegister als JSON-bestand voor back-up of migratie.

POST
/api/vault/import

Coderegister importeren

Importeer een eerder geëxporteerd coderegister (JSON) om codetoewijzingen te herstellen.

Status

GET
/health

Statuscontrole

Geeft de status van de server terug. Gebruik dit voor monitoring en voor de statuscontroles van de load balancer.

Instellingen

GET
/api/settings

Instellingen ophalen

Haal de huidige detectie- en verwerkingsconfiguratie op (drempels, ingeschakelde pipelines, taal enz.).

PATCH
/api/settings

Instellingen bijwerken

Werk de globale detectie-instellingen gedeeltelijk bij. Wijzigingen gelden voor alle volgende detectieruns.

GET
/api/settings/patterns

Lijst van eigen patronen

Haal alle door de gebruiker gedefinieerde regex-patronen op die voor eigen PII-detectie worden gebruikt.

POST
/api/settings/patterns

Eigen patroon aanmaken

Voeg een nieuw eigen regex-patroon toe voor PII-detectie. Patronen worden samen met de ingebouwde regels geëvalueerd.

Voorbeeld

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

De klasse PromptShield voert de volledige pipeline lokaal uit: detecteren, anonimiseren en detokeniseren in drie aanroepen. Alle verwerking gebeurt op uw apparaat; er verlaten geen documentgegevens uw apparaat.

De SDK wordt meegeleverd met het Python-pakket, dat nog niet op PyPI staat. Tot die tijd doen de HTTP-endpoints hierboven hetzelfde werk.

Python SDK
bash
from promptshield import PromptShield

ps = PromptShield()

# PII detecteren
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']}")

# Anonimiseren (omkeerbare tokenisering)
out = ps.anonymize("contract.pdf", "contract-safe.pdf")
print(f"Done: {out.tokens_created} tokens created")

# De oorspronkelijke waarden herstellen
restored = ps.detokenize("contract-safe.pdf", "contract-restored.pdf")
print(f"Restored {restored.tokens_replaced} tokens")

Foutafhandeling

Alle foutantwoorden hebben een standaard JSON-formaat met een detail-veld dat de fout beschrijft.

400

Ongeldige aanvraag. Onjuiste parameters of een beschadigd / niet-ondersteund bestand.

401

Niet geautoriseerd. Ontbrekende of ongeldige API-sleutel (Authorization: Bearer) in de API-sleutelmodus.

403

Verboden. De API-sleutel mist de vereiste scope (detect / anonymize / detokenize).

404

Niet gevonden. De document-ID bestaat niet.

422

Niet verwerkbaar. Een verplicht veld ontbreekt, of het bestand is met een wachtwoord beveiligd.

500

Serverfout. Raadpleeg de serverlogboeken voor details.

503

Een vereist detectiemodel is niet geïnstalleerd. Installeer het met promptshield models install.

Error Response Format
bash
{
  "detail": "Document not found: abc123"
}

Aanvraaglimieten

De zelfgehoste API accepteert standaard tot 6.000 aanvragen per minuut per client-IP. Wijzig die limiet met de omgevingsvariabele PROMPTSHIELD_SELF_HOSTED_RATE.