Developers
Référence de l'API

Documentation de l'API

Référence complète de l'API REST du moteur promptShield auto-hébergé. Tous les points d'accès sont disponibles à l'URL de votre déploiement.

URL de base

http://localhost:8000

Remplacez par l'hôte et le port de votre déploiement.

Schéma OpenAPI

Le serveur expose /docs (Swagger UI), /redoc et /openapi.json. En mode clé API, les trois exigent l'en-tête Authorization : un navigateur ne peut donc pas les ouvrir directement. Récupérez le schéma et chargez-le dans un client capable d'envoyer un en-tête :

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

Un navigateur ne peut pas envoyer l'en-tête Authorization lors d'une navigation : /docs répond donc 401 en mode clé API. Le schéma ci-dessus est la voie utilisable.

Authentification

Lorsque PROMPTSHIELD_API_KEY est définie (via promptshield serve --api-key ou la variable d'environnement Docker), chaque requête doit la fournir sous la forme Authorization: Bearer <api-key> ; une clé manquante ou incorrecte renvoie 401, et une clé limitée à certaines opérations renvoie 403 sur les autres. Le point d'accès /health en est toujours exempté. Si aucune clé API n'est définie, le serveur fonctionne sans authentification et accepte toutes les requêtes, ce qui ne convient que sur un réseau local de confiance.

Démarrage rapide

Mettez l'API locale en route avec Docker. Le premier téléchargement pèse environ 3,8 Go.

1

Récupérer votre clé API

bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

Votre clé API est disponible dans le tableau de bord des clés API.

2

Démarrer le serveur

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

L'image embarque Tesseract OCR, LibreOffice et les modèles de détection pour l'anglais et le français. Installez les autres langues avec promptshield models install.

3

Vérifier que le serveur tourne

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

Traiter votre premier document

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

Vous préférez une installation Python locale ?

Le paquet Python n'est pas encore sur PyPI : pip install promptshield-app ne fonctionnera donc pas. Utilisez l'image Docker ci-dessus ou compilez depuis les sources. Cette page sera mise à jour dès la publication du paquet.

Guide pas à pas

Un guide complet pour mettre en place l'API locale et l'intégrer à vos processus.

1. Prérequis

Avant de commencer, assurez-vous d'avoir installé les éléments suivants :

Docker (l'installation prise en charge aujourd'hui)
Python 3.11 ou ultérieur
pip (inclus avec Python)
Une clé API promptShield (offre Pro)

Facultatif, pour une prise en charge complète des formats :

Tesseract OCR, pour les PDF numérisés ou à base d'images
LibreOffice : inutile pour les fichiers .docx, .xlsx, .xls et .pptx, convertis en Python

2. Installer le SDK

Installez le paquet Python de promptShield. L'installation de base gère les fichiers PDF. Ajoutez l'extra office pour Word, Excel et PowerPoint.

Le paquet Python n'est pas encore publié sur PyPI : les deux commandes ci-dessous ne fonctionneront pas. Utilisez pour l'instant l'image Docker de la section 5. Tout le reste de cette page s'applique aux deux.

Installation de base (PDF uniquement)
bash
pip install promptshield-app
Avec la prise en charge des formats Office
bash
pip install "promptshield-app[office]"

Installez les modèles de langue (les packs d'entités) via le 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

Installez des packs de langue supplémentaires de la même manière :

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

L'API locale utilise votre clé API promptShield pour la validation de la licence. Définissez-la comme variable d'environnement, ou passez-la au démarrage du serveur.

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

La clé API est validée en ligne au démarrage, puis toutes les 6 heures. Chaque réponse est mise en cache localement : si le serveur de licences est injoignable, le serveur continue de fonctionner jusqu'à 3 jours.

4. Démarrer le serveur d'API

Lancez le serveur local d'une seule commande :

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.

Options disponibles :

--hostAdresse de liaison (par défaut : 127.0.0.1)
--portPort de liaison (par défaut : 8000)
--api-keyClé API (alternative à la variable d'environnement)

Une fois démarrée, l'API est accessible à l'URL affichée. Le schéma OpenAPI se trouve à /openapi.json ; envoyez aussi votre clé API avec cette requête.

5. Déploiement avec Docker

En production, Docker évite toute installation : les dépendances sont déjà incluses.

Conteneur unique
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
Avec 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:

Créez un fichier .env contenant votre clé API :

.env
bash
PROMPTSHIELD_API_KEY=ps_live_your_key_here

L'image Docker inclut :

Tesseract OCR avec 8 packs de langue (EN, FR, DE, ES, IT, NL, PT, PL)
LibreOffice pour la conversion des formats Office
Modèles spaCy anglais et français préinstallés (autres langues via models install)
Un utilisateur non root, des vérifications de santé, un volume de données persistant

6. Les étapes d'un traitement par l'API

Le traitement standard d'un document comporte 5 étapes :

1Importer : envoyez votre document au serveur
2Détecter : exécutez le pipeline de détection des données personnelles (motifs + entités + LLM facultatif)
3Relire : inspectez les régions détectées, modifiez-les ou confirmez-les
4Anonymiser : remplacez les données personnelles par des codes
5Télécharger : récupérez le document anonymisé

Exemple complet de traitement (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. Commandes du CLI

Traitez vos documents directement en ligne de commande, sans démarrer de serveur :

Détecter les données personnelles et enregistrer un rapport JSON
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
Anonymiser un document en une seule étape
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
Restaurer les valeurs d'origine d'un document précédemment anonymisé
bash
promptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdf

Toutes les commandes du CLI valident votre clé API et traitent les documents localement. Aucune donnée de vos documents ne quitte votre appareil.

Modules de modèles

Utilisez la commande models intégrée pour parcourir, installer et supprimer les packs de langue d'entités. Définissez PROMPTSHIELD_ASSETS_DIR pour que le CLI et le serveur en cours d'exécution les trouvent tous deux.

Définissez le répertoire d'installation une fois pour toutes (ajoutez-le à votre profil shell) :
bash
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
Parcourir les packs disponibles avec leur statut d'installation
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)  ...
Télécharger et installer un pack (aucun serveur requis)
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
Lister les packs installés dans PROMPTSHIELD_ASSETS_DIR
bash
promptshield models installed
# Installed models:
#   spacy-en-md   English (medium)
#   spacy-fr-md   French (medium)
Supprimer un pack
bash
promptshield models remove spacy-fr-md

Les packs installés sont automatiquement pris en compte par detect, anonymize et le serveur d'API en cours d'exécution. La commande install communique directement avec le serveur de licences : aucun sidecar n'a besoin de tourner.

8. Expressions personnalisées

Les motifs et la détection d'entités intégrés couvrent la plupart des données personnelles, mais chaque organisation a ses propres identifiants : numéros de contrat, codes de projet internes, identifiants fiscaux, indicateurs de confidentialité. Ajoutez-les comme expressions et ils seront traités comme des données personnelles à part entière, étiquetés du type CUSTOM, avec une zone de délimitation complète et une propagation d'une page à l'autre. Disponible dans le CLI (-e / --expression), dans l'API HTTP auto-hébergée (blacklist_terms) et via les préréglages de demo/setup.json.

CLI : option -e / --expression, répétable
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]+"
API HTTP : corps de 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.
Fichier de préréglages : appliqué à chaque appel --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

À propos du nom : expressions est désormais le nom canonique partout : dans le CLI (-e / --expression), dans l'API HTTP (expressions / expressions_action / expressions_fuzziness) et dans le libellé de l'interface de bureau. Les anciennes clés blacklist_terms / blacklist_action / blacklist_fuzziness de l'API HTTP restent acceptées grâce à un alias Pydantic, par souci de rétrocompatibilité : les intégrations existantes continuent donc de fonctionner.

Le circuit de relecture : API → application de bureau

À grande échelle, la détection automatisée ne fait que la moitié du chemin : elle n'atteint jamais une précision de 100 %, et il reste toujours des faux positifs à écarter et des entités manquées à ajouter. promptShield boucle la boucle avec une archive .psreview portable : détectez par programmation, importez le résultat dans l'application de bureau pour une vérification humaine à l'écran, puis anonymisez.

📂
Détection par lots
API ou CLI
📦
Archive .psreview
document + annotations
🖥️
Relecture dans l'application de bureau
écarter les faux positifs · ajouter les données personnelles manquées
✅
PDF anonymisés

Étape 1a : détecter et exporter (CLI, en une commande)

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

Étape 1b : détecter et exporter (API HTTP)

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

Exporter l'archive de relecture

Téléchargez le document et toutes ses annotations de régions sous forme d'archive .psreview portable (ZIP).

POST
/api/documents/import-review

Importer l'archive de relecture

Importez une archive .psreview. Ce point d'accès extrait le document (en exécutant l'OCR), injecte les annotations de régions enregistrées et ouvre le document au statut REVIEWING, prêt pour une vérification visuelle, sans relancer la détection.

Étape 2 : relire, modifier et anonymiser

Utilisez la barre latérale des régions pour écarter les faux positifs (réglez l'action sur Annuler), tracez de nouvelles régions pour ce que le modèle a manqué, puis cliquez sur Télécharger. L'application de bureau procède à l'anonymisation et enregistre le PDF caviardé dans votre dossier Téléchargements.

8. SDK Python (import direct)

Pour les intégrations avancées, importez les modules du cœur directement dans votre code Python. Vous gardez ainsi le contrôle total de chaque étape du traitement.

Exemple Python complet
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

Exemple de traitement par lots

Traiter plusieurs fichiers d'un répertoire :

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. Sécurité et confidentialité des données

promptShield est conçu pour les environnements zero-trust :

Tout le traitement se déroule localement : aucun contenu de document n'est jamais envoyé à des serveurs externes
Le registre de codes reste sur votre appareil, dans le même périmètre de confiance que vos documents sources, et n'est jamais transféré
L'authentification par clé API empêche tout accès non autorisé en mode auto-hébergé
Docker s'exécute en tant qu'utilisateur non root, avec des privilèges minimaux
La clé API est validée en ligne au démarrage puis toutes les 6 heures, et mise en cache localement (3 jours maximum hors ligne)

10. Dépannage

Problèmes courants et solutions :

Erreur « No spaCy model found » ou « no NER model loaded »

Définissez PROMPTSHIELD_ASSETS_DIR et installez un pack : promptshield models install spacy-en-md. Pour une installation à l'échelle du système : python -m spacy download en_core_web_sm

L'OCR ne fonctionne pas sur les PDF numérisés

Installez Tesseract OCR et assurez-vous qu'il figure dans votre PATH. Sous Windows, l'installeur l'ajoute automatiquement.

La conversion des fichiers Office échoue

Les fichiers Word, Excel et PowerPoint (.docx, .xlsx, .xls, .pptx) sont convertis en Python, sans LibreOffice. Vérifiez que l'extra office est installé et que le fichier n'est pas protégé par un mot de passe.

« Invalid API key » au démarrage

Vérifiez que votre clé commence par ps_live_ et que votre abonnement est actif. Les clés se gèrent depuis /developers/api-keys.

Documents

POST
/api/documents/upload

Importer un document

Importez un document à traiter. Prend en charge les fichiers PDF, DOCX, XLSX, PPTX et les images.

GET
/api/documents

Lister les documents

Récupérez tous les documents importés, avec leur statut de détection et d'anonymisation.

GET
/api/documents/{id}

Obtenir un document

Obtenez les informations détaillées d'un document précis, y compris son nombre de pages et son statut de détection.

DELETE
/api/documents/{id}

Supprimer un document

Supprimez un document et toutes les données associées du serveur.

Détection

POST
/api/documents/{id}/detect

Détecter les données personnelles

Exécutez le pipeline de détection des données personnelles sur un document. Accepte un corps JSON facultatif pour remplacer les paramètres de détection (confidence_threshold, regex_enabled, ner_enabled, regex_types, etc.) pour cette seule exécution.

POST
/api/documents/{id}/redetect

Relancer la détection

Relancez la détection avec un contrôle complet des paramètres. Accepte confidence_threshold, regex_types, ner_types, blacklist_terms et bien d'autres.

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

Progression de la détection

Obtenez la progression d'une tâche de détection en cours (pourcentage, page courante et statut).

GET
/api/documents/{id}/regions

Obtenir les régions

Récupérez toutes les régions de données personnelles détectées pour un document, avec leur type, leur texte, leur score de confiance et leur zone de délimitation.

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

Mettre à jour des régions en lot

Définissez l'action (TOKENIZE, REMOVE ou CANCEL) pour plusieurs régions à la fois, filtrées par type d'entité.

Anonymisation et export

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

Synchroniser les régions

Remplacez entièrement la liste des régions d'un document. À utiliser après avoir modifié les régions côté client, pour envoyer les changements avant l'anonymisation.

POST
/api/documents/{id}/anonymize

Anonymiser un document

Anonymisez un document en remplaçant les données personnelles détectées par des codes. Renvoie le document traité.

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

Télécharger le document anonymisé

Téléchargez le résultat anonymisé. {type} vaut « pdf » ou « text ». Le résultat est toujours rendu en PDF (les fichiers non PDF sont convertis), si bien que « pdf » est le format principal.

POST
/api/documents/batch-anonymize

Anonymiser en lot

Anonymisez plusieurs documents en une seule requête : jusqu'à 50 par requête, traités 3 à la fois.

Décodage

POST
/api/detokenize

Décoder du texte

Remplacez les codes d'une chaîne de texte par leurs valeurs d'origine issues du coffre.

POST
/api/detokenize/file

Décoder un fichier

Importez un document encodé et recevez une version dont tous les codes ont retrouvé leurs valeurs d'origine.

Coffre et registre de codes

GET
/api/vault/status

État du coffre

Obtenez les statistiques du coffre : nombre total de codes, nombre total de documents, taille du registre.

GET
/api/vault/tokens

Lister les codes

Récupérez toutes les correspondances code-valeur d'origine stockées dans le coffre.

POST
/api/vault/export

Exporter le coffre

Exportez l'intégralité du coffre dans un fichier JSON, pour sauvegarde ou migration.

POST
/api/vault/import

Importer le coffre

Importez un coffre JSON précédemment exporté pour restaurer les correspondances de codes.

État de santé

GET
/health

Vérification de l'état de santé

Renvoie l'état de santé du serveur. À utiliser pour la supervision et les sondes de santé d'un répartiteur de charge.

Paramètres

GET
/api/settings

Obtenir les paramètres

Récupérez la configuration actuelle de détection et de traitement (seuils, pipelines activés, langue, etc.).

PATCH
/api/settings

Modifier les paramètres

Mettez à jour partiellement les paramètres globaux de détection. Les changements s'appliquent à toutes les détections suivantes.

GET
/api/settings/patterns

Lister les motifs personnalisés

Obtenez tous les motifs définis par l'utilisateur, utilisés pour la détection personnalisée des données personnelles.

POST
/api/settings/patterns

Créer un motif personnalisé

Ajoutez un nouveau motif pour la détection des données personnelles. Les motifs sont évalués en plus des règles intégrées.

Exemple

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

SDK Python

La classe PromptShield exécute tout le pipeline localement — détecter, anonymiser et décoder en trois appels. Tout le traitement se déroule sur votre appareil ; aucune donnée de vos documents n'en sort.

Le SDK est livré avec le paquet Python, qui n'est pas encore sur PyPI. En attendant, les points d'accès HTTP ci-dessus font le même travail.

Python SDK
bash
from promptshield import PromptShield

ps = PromptShield()

# Détecter les données personnelles
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']}")

# Anonymiser (tokenisation réversible)
out = ps.anonymize("contract.pdf", "contract-safe.pdf")
print(f"Done: {out.tokens_created} tokens created")

# Restaurer les valeurs d'origine
restored = ps.detokenize("contract-safe.pdf", "contract-restored.pdf")
print(f"Restored {restored.tokens_replaced} tokens")

Gestion des erreurs

Toutes les réponses d'erreur suivent un format JSON standard, avec un champ detail décrivant l'erreur.

400

Requête incorrecte. Paramètres invalides, ou fichier corrompu / non pris en charge.

401

Non autorisé. Clé API manquante ou invalide (Authorization: Bearer) en mode clé API.

403

Interdit. La clé API ne dispose pas de la portée requise (detect / anonymize / detokenize).

404

Introuvable. L'identifiant du document n'existe pas.

422

Non traitable. Un champ obligatoire est manquant, ou le fichier est protégé par mot de passe.

500

Erreur serveur. Consultez les journaux du serveur pour plus de détails.

503

Un modèle de détection requis n'est pas installé. Installez-le avec promptshield models install.

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

Limites de débit

Par défaut, l'API auto-hébergée accepte jusqu'à 6 000 requêtes par minute et par adresse IP cliente. Pour modifier cette limite, définissez la variable d'environnement PROMPTSHIELD_SELF_HOSTED_RATE.