API-referentie

API documentatie

Volledige REST-API-referentie voor de zelfgehoste promptShield-engine. Alle eindpunten zijn beschikbaar op uw implementatie-URL.

Basis-URL

http://localhost:8000

Vervang door de host en poort van uw implementatie.

Interactieve API-documentatie

Wanneer de server draait, bezoekt u /docs voor een automatisch gegenereerde interactieve Swagger UI waar u elk eindpunt rechtstreeks kunt testen.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

In API-key mode, /docs, /openapi.json, and /redoc require Authorization: Bearer <api-key>.

Authenticatie

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

Snel aan de slag

Krijg de lokale API in minder dan 5 minuten draaiend.

Het pakket installeren

bash

pip install promptshield-app

Een taalmodel installeren

bash

export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
promptshield models install spacy-en-md

Uw API-sleutel instellen

bash

export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

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

De server starten

bash

promptshield serve --port 8000

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": "REVIEWING"}

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

Of draai met Docker (geen installatie)

bash

docker run -e PROMPTSHIELD_API_KEY="ps_live_your_key_here" \
  -p 8000:8000 -v promptshield-data:/data \
  promptshield/promptshield-api:latest

Stapsgewijze handleiding

Een uitgebreide doorloop om de lokale API in te stellen en in uw workflow te integreren.

1. Vereisten

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

Python 3.11 of nieuwer

pip (inbegrepen bij Python)

Een promptShield-API-sleutel (Basic- of Pro-abonnement)

Optioneel. voor volledige formaatondersteuning:

Tesseract OCR. voor gescande/op afbeeldingen gebaseerde PDF's

LibreOffice. voor de conversie van .docx, .xlsx, .pptx

2. De SDK installeren

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

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 tot 35 dagen lokaal gecachet, zodat de server na de eerste start volledig offline kan draaien.

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 endpoint: http://127.0.0.1:8000/health
# Docs: enable with PROMPTSHIELD_DEBUG_API_DOCS=1 in non-API-key mode

Beschikbare opties:

--host	Bind-adres (standaard: 127.0.0.1)
--port	Bind-poort (standaard: 8000)
--api-key	API-sleutel (alternatief voor de omgevingsvariabele)

Eenmaal gestart is de API beschikbaar op de getoonde URL. Interactieve Swagger-documentatie staat op /docs.

5. Docker-implementatie (alternatief)

Voor productie-implementaties biedt Docker een installatievrije ervaring met alle afhankelijkheden gebundeld.

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 7 taalpakketten (EN, FR, DE, ES, IT, NL, PT)

LibreOffice voor de conversie van Office-formaten

spaCy NLP-modellen vooraf geïnstalleerd

Non-root-gebruiker, gezondheidscontroles, persistent gegevensvolume

6. API-workflow

De standaardworkflow voor documentverwerking heeft 5 stappen:

1Uploaden. Stuur uw document naar de server

2Detecteren. Voer de PII-detectiepijplijn uit (regex + entiteiten + optioneel LLM)

3Beoordelen. Inspecteer gedetecteerde gebieden, 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 gegevens uw apparaat.

Model-add-ons

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

Stel de installatiemap eenmalig in (voeg 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 bladeren 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

Pakketten opsommen die zijn geïnstalleerd in PROMPTSHIELD_ASSETS_DIR

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 opgepikt door detect, anonymize en de draaiende API-server. De opdracht install praat rechtstreeks met de licentieserver — geen draaiende sidecar nodig.

8. Eigen expressies

Ingebouwde regex en entiteiten dekken de meeste PII, maar elke organisatie heeft eigen identificatoren — contractnummers, interne projectcodes, fiscale nummers, vertrouwelijkheidsmarkeringen. Voeg ze toe als expressies en ze worden behandeld als eersteklas PII, gemarkeerd als type CUSTOM met volledig bbox + propagatie over pagina's heen. Beschikbaar op de CLI (-e / --expression), op de zelfgehoste HTTP-API (blacklist_terms) en via demo/setup.json-presets.

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 --preset <locale>-aanroep

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 over alle drie de oppervlakken — 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 op de HTTP-API werken nog steeds via een Pydantic-alias voor achterwaartse compatibiliteit, zodat bestaande integraties blijven werken.

Beoordelingsworkflow: API → desktop

Geautomatiseerde detectie op schaal is maar de helft van het verhaal. Automatische detectie haalt nooit 100% precisie — er zijn altijd valse positieven om af te wijzen en gemiste entiteiten om toe te voegen. promptShield sluit de cirkel met een draagbare .psreview-bundel: detecteer programmatisch, importeer in de desktop-app voor visuele menselijke QA 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 gebiedsannotaties als een draagbare .psreview-ZIP-bundel.

POST

/api/documents/import-review

Beoordelingsbundel importeren

Upload een .psreview-bundel. Pakt het document uit (voert OCR uit), injecteert de opgeslagen gebiedsannotaties en opent het document in de status REVIEWING — klaar voor visuele QA zonder de detectie opnieuw uit te voeren.

Stap 2 — Importeren in de desktop-app

Open de promptShield-desktop-app. Klik op het uploadscherm op Importeren voor beoordeling en selecteer het .psreview-bestand. Het document opent direct in beoordelingsmodus — alle gedetecteerde gebieden zijn vooraf ingevuld, geen detectiestap nodig.

Stap 3 — Beoordelen, bewerken en anonimiseren

Gebruik de gebiedszijbalk om valse positieven af te wijzen (actie op Annuleren zetten), teken nieuwe gebieden voor alles wat het model heeft gemist en klik daarna op Exporteren. De desktop-app voert de anonimisering uit en slaat de geredigeerde 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 — dezelfde vertrouwensgrens als uw brondocumenten, nooit geüpload

API-sleutelauthenticatie voorkomt ongeoorloofde toegang in de zelfgehoste modus

Docker draait als non-root met minimale privileges

API-sleutel eenmaal online gevalideerd, daarna lokaal gecachet voor offline gebruik (TTL van 35 dagen)

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

Installeer LibreOffice. DOCX heeft een pure-Python-fallback, maar XLSX/PPTX vereisen LibreOffice.

'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 opsommen

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

GET

/api/documents/{id}

Document ophalen

Verkrijg gedetailleerde informatie over een specifiek document, inclusief paginatelling en 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-detectiepijplijn 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

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

GET

/api/documents/{id}/regions

Gebieden ophalen

Haal alle gedetecteerde PII-gebieden voor een document op met type, tekst, betrouwbaarheidsscore en selectiekader.

PUT

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

Gebieden in batch bijwerken

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

Anonimiseren & exporteren

PUT

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

Gebieden synchroniseren

Vervang de gebiedslijst van een document volledig. Gebruik dit na het bewerken van gebieden aan de clientzijde om wijzigingen door te zetten vóór het anonimiseren.

POST

/api/documents/{id}/anonymize

Document anonimiseren

Anonimiseer een document door gedetecteerde PII door codes te vervangen. 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 enkele aanvraag. Tot 50 documenten gelijktijdig verwerkt.

Decoderen

POST

/api/detokenize

Tekst decoderen

Vervang codes in een tekstreeks door hun oorspronkelijke waarden uit de kluis.

POST

/api/detokenize/file

Bestand decoderen

Upload een gecodeerd document en ontvang een versie waarin alle codes naar de oorspronkelijke waarden zijn hersteld.

Kluis & coderegister

GET

/api/vault/status

Kluisstatus

Verkrijg kluisstatistieken: totaal aantal codes, totaal aantal documenten, registergrootte.

GET

/api/vault/tokens

Codes opsommen

Haal alle code-naar-origineel-toewijzingen op die in de kluis zijn opgeslagen.

POST

/api/vault/export

Kluis exporteren

Exporteer de volledige kluis als JSON-bestand voor back-up of migratie.

POST

/api/vault/import

Kluis importeren

Importeer een eerder geëxporteerde kluis-JSON om codetoewijzingen te herstellen.

Gezondheid

GET

/health

Gezondheidscontrole

Geeft de gezondheidsstatus van de server terug. Gebruik dit voor bewaking en gezondheidscontroles van de load balancer.

Instellingen

GET

/api/settings

Instellingen ophalen

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

PATCH

/api/settings

Instellingen bijwerken

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

GET

/api/settings/patterns

Eigen patronen opsommen

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": "REVIEWING"}

# 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 pijplijn lokaal uit — detecteren, anonimiseren en detokeniseren in drie aanroepen. Alle verwerking gebeurt op uw apparaat; er verlaat geen gegevens uw apparaat.

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 foutreacties volgen 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"
}

Snelheidslimieten

De zelfgehoste API heeft standaard geen snelheidslimieten. U kunt indien nodig snelheidsbeperking configureren via omgevingsvariabelen.

Developers

API-referentie

API documentatie

Volledige REST-API-referentie voor de zelfgehoste promptShield-engine. Alle eindpunten zijn beschikbaar op uw implementatie-URL.

Basis-URL

http://localhost:8000

Vervang door de host en poort van uw implementatie.

Interactieve API-documentatie

Wanneer de server draait, bezoekt u /docs voor een automatisch gegenereerde interactieve Swagger UI waar u elk eindpunt rechtstreeks kunt testen.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

In API-key mode, /docs, /openapi.json, and /redoc require Authorization: Bearer <api-key>.

Authenticatie

Snel aan de slag

Krijg de lokale API in minder dan 5 minuten draaiend.

Het pakket installeren

bash

pip install promptshield-app

Een taalmodel installeren

bash

export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
promptshield models install spacy-en-md

Uw API-sleutel instellen

bash

export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

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

De server starten

bash

promptshield serve --port 8000

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": "REVIEWING"}

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

Of draai met Docker (geen installatie)

bash

docker run -e PROMPTSHIELD_API_KEY="ps_live_your_key_here" \
  -p 8000:8000 -v promptshield-data:/data \
  promptshield/promptshield-api:latest

Stapsgewijze handleiding

Een uitgebreide doorloop om de lokale API in te stellen en in uw workflow te integreren.

1. Vereisten

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

Python 3.11 of nieuwer

pip (inbegrepen bij Python)

Een promptShield-API-sleutel (Basic- of Pro-abonnement)

Optioneel. voor volledige formaatondersteuning:

Tesseract OCR. voor gescande/op afbeeldingen gebaseerde PDF's

LibreOffice. voor de conversie van .docx, .xlsx, .pptx

2. De SDK installeren

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

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 tot 35 dagen lokaal gecachet, zodat de server na de eerste start volledig offline kan draaien.

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 endpoint: http://127.0.0.1:8000/health
# Docs: enable with PROMPTSHIELD_DEBUG_API_DOCS=1 in non-API-key mode

Beschikbare opties:

--host	Bind-adres (standaard: 127.0.0.1)
--port	Bind-poort (standaard: 8000)
--api-key	API-sleutel (alternatief voor de omgevingsvariabele)

Eenmaal gestart is de API beschikbaar op de getoonde URL. Interactieve Swagger-documentatie staat op /docs.

5. Docker-implementatie (alternatief)

Voor productie-implementaties biedt Docker een installatievrije ervaring met alle afhankelijkheden gebundeld.

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 7 taalpakketten (EN, FR, DE, ES, IT, NL, PT)

LibreOffice voor de conversie van Office-formaten

spaCy NLP-modellen vooraf geïnstalleerd

Non-root-gebruiker, gezondheidscontroles, persistent gegevensvolume

6. API-workflow

De standaardworkflow voor documentverwerking heeft 5 stappen:

1Uploaden. Stuur uw document naar de server

2Detecteren. Voer de PII-detectiepijplijn uit (regex + entiteiten + optioneel LLM)

3Beoordelen. Inspecteer gedetecteerde gebieden, 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 gegevens uw apparaat.

Model-add-ons

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

Stel de installatiemap eenmalig in (voeg 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 bladeren 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

Pakketten opsommen die zijn geïnstalleerd in PROMPTSHIELD_ASSETS_DIR

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 opgepikt door detect, anonymize en de draaiende API-server. De opdracht install praat rechtstreeks met de licentieserver — geen draaiende sidecar nodig.

8. Eigen expressies

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 --preset <locale>-aanroep

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

Beoordelingsworkflow: API → desktop

📂

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 gebiedsannotaties als een draagbare .psreview-ZIP-bundel.

POST

/api/documents/import-review

Beoordelingsbundel importeren

Stap 2 — Importeren in de desktop-app

Stap 3 — Beoordelen, bewerken en anonimiseren

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 — dezelfde vertrouwensgrens als uw brondocumenten, nooit geüpload

API-sleutelauthenticatie voorkomt ongeoorloofde toegang in de zelfgehoste modus

Docker draait als non-root met minimale privileges

API-sleutel eenmaal online gevalideerd, daarna lokaal gecachet voor offline gebruik (TTL van 35 dagen)

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

Installeer LibreOffice. DOCX heeft een pure-Python-fallback, maar XLSX/PPTX vereisen LibreOffice.

'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 opsommen

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

GET

/api/documents/{id}

Document ophalen

Verkrijg gedetailleerde informatie over een specifiek document, inclusief paginatelling en 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

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

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

GET

/api/documents/{id}/regions

Gebieden ophalen

Haal alle gedetecteerde PII-gebieden voor een document op met type, tekst, betrouwbaarheidsscore en selectiekader.

PUT

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

Gebieden in batch bijwerken

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

Anonimiseren & exporteren

PUT

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

Gebieden synchroniseren

Vervang de gebiedslijst van een document volledig. Gebruik dit na het bewerken van gebieden aan de clientzijde om wijzigingen door te zetten vóór het anonimiseren.

POST

/api/documents/{id}/anonymize

Document anonimiseren

Anonimiseer een document door gedetecteerde PII door codes te vervangen. 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 enkele aanvraag. Tot 50 documenten gelijktijdig verwerkt.

Decoderen

POST

/api/detokenize

Tekst decoderen

Vervang codes in een tekstreeks door hun oorspronkelijke waarden uit de kluis.

POST

/api/detokenize/file

Bestand decoderen

Upload een gecodeerd document en ontvang een versie waarin alle codes naar de oorspronkelijke waarden zijn hersteld.

Kluis & coderegister

GET

/api/vault/status

Kluisstatus

Verkrijg kluisstatistieken: totaal aantal codes, totaal aantal documenten, registergrootte.

GET

/api/vault/tokens

Codes opsommen

Haal alle code-naar-origineel-toewijzingen op die in de kluis zijn opgeslagen.

POST

/api/vault/export

Kluis exporteren

Exporteer de volledige kluis als JSON-bestand voor back-up of migratie.

POST

/api/vault/import

Kluis importeren

Importeer een eerder geëxporteerde kluis-JSON om codetoewijzingen te herstellen.

Gezondheid

GET

/health

Gezondheidscontrole

Geeft de gezondheidsstatus van de server terug. Gebruik dit voor bewaking en gezondheidscontroles van de load balancer.

Instellingen

GET

/api/settings

Instellingen ophalen

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

PATCH

/api/settings

Instellingen bijwerken

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

GET

/api/settings/patterns

Eigen patronen opsommen

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": "REVIEWING"}

# 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

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 foutreacties volgen 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"
}

Snelheidslimieten

De zelfgehoste API heeft standaard geen snelheidslimieten. U kunt indien nodig snelheidsbeperking configureren via omgevingsvariabelen.