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.

Documentation d'API interactive

Lorsque le serveur est en cours d'exécution, rendez-vous sur /docs pour une interface Swagger interactive générée automatiquement, où vous pouvez tester directement chaque point d'accès.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

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 en moins de 5 minutes.

Installer le paquet

bash

pip install promptshield-app

Installer un modèle de langue

bash

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

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

Démarrer le serveur

bash

promptshield serve --port 8000

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

Ou lancez-la avec Docker (aucune installation)

bash

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

Guide pas à pas

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

1. Prérequis

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

Python 3.11 ou ultérieur

pip (inclus avec Python)

Une clé API promptShield (offre Basic ou Pro)

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

Tesseract OCR, pour les PDF numérisés ou à base d'images

LibreOffice, pour la conversion des fichiers .docx, .xlsx, .pptx

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.

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 mise en cache localement pour une durée maximale de 35 jours : le serveur peut ainsi fonctionner entièrement hors ligne après le premier lancement.

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

Options disponibles :

--host	Adresse de liaison (par défaut : 127.0.0.1)
--port	Port de liaison (par défaut : 8000)
--api-key	Clé API (alternative à la variable d'environnement)

Une fois démarrée, l'API est accessible à l'URL affichée. La documentation Swagger interactive se trouve à /docs.

5. Déploiement avec Docker (alternative)

Pour les déploiements en production, Docker offre une expérience sans installation, toutes les dépendances étant 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 7 packs de langue (EN, FR, DE, ES, IT, NL, PT)

LibreOffice pour la conversion des formats Office

Les modèles de TAL spaCy préinstallés

Un utilisateur non root, des vérifications de santé, un volume de données persistant

6. Le workflow de l'API

Le workflow standard de traitement 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 workflow (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 codes 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 ne quitte votre machine.

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 : ils sont alors 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 sur les trois surfaces — le CLI (-e / --expression), l'API HTTP (expressions / expressions_action / expressions_fuzziness) et le libellé de l'interface de bureau. Les anciennes clés blacklist_terms / blacklist_action / blacklist_fuzziness de l'API HTTP fonctionnent toujours grâce à un alias Pydantic, par souci de rétrocompatibilité : les intégrations existantes continuent donc de fonctionner.

Le workflow de relecture : API → application de bureau

La détection automatisée à grande échelle ne fait que la moitié du chemin. La détection automatique n'atteint jamais une précision de 100 % — il y a toujours des faux positifs à écarter et des entités manquées à ajouter. promptShield boucle la boucle avec un bundle .psreview portable : détectez par programmation, importez dans l'application de bureau pour une vérification humaine visuelle, puis anonymisez.

📂

Détection par lots

API ou CLI

📦

Bundle .psreview

document + annotations

🖥️

Relecture sur 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 le bundle de relecture

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

POST

/api/documents/import-review

Importer le bundle de relecture

Importez un bundle .psreview. Il extrait le document (exécute 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 — Importer dans l'application de bureau

Ouvrez l'application de bureau promptShield. Sur l'écran d'import, cliquez sur Importer pour relecture et sélectionnez le fichier .psreview. Le document s'ouvre aussitôt en mode relecture — toutes les régions détectées sont préremplies, sans aucune étape de détection.

Étape 3 — 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 Exporter. 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 machine — 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 une fois en ligne, puis mise en cache localement pour un usage hors ligne (durée de vie de 35 jours)

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'installateur l'ajoute automatiquement.

La conversion des fichiers Office échoue

Installez LibreOffice. Le format DOCX dispose d'une solution de repli en pur Python, mais les formats XLSX/PPTX nécessitent LibreOffice.

« 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 pousser 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 documents traités en parallèle.

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 aux côtés 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": "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

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 machine ; aucune donnée n'en sort.

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

L'API auto-hébergée n'impose aucune limite de débit par défaut. Vous pouvez configurer une limitation de débit à l'aide de variables d'environnement, au besoin.

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.

Documentation d'API interactive

Lorsque le serveur est en cours d'exécution, rendez-vous sur /docs pour une interface Swagger interactive générée automatiquement, où vous pouvez tester directement chaque point d'accès.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

Authentification

Démarrage rapide

Mettez l'API locale en route en moins de 5 minutes.

Installer le paquet

bash

pip install promptshield-app

Installer un modèle de langue

bash

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

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

Démarrer le serveur

bash

promptshield serve --port 8000

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

Ou lancez-la avec Docker (aucune installation)

bash

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

Guide pas à pas

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

1. Prérequis

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

Python 3.11 ou ultérieur

pip (inclus avec Python)

Une clé API promptShield (offre Basic ou Pro)

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

Tesseract OCR, pour les PDF numérisés ou à base d'images

LibreOffice, pour la conversion des fichiers .docx, .xlsx, .pptx

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.

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"

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

Options disponibles :

--host	Adresse de liaison (par défaut : 127.0.0.1)
--port	Port de liaison (par défaut : 8000)
--api-key	Clé API (alternative à la variable d'environnement)

Une fois démarrée, l'API est accessible à l'URL affichée. La documentation Swagger interactive se trouve à /docs.

5. Déploiement avec Docker (alternative)

Pour les déploiements en production, Docker offre une expérience sans installation, toutes les dépendances étant 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 7 packs de langue (EN, FR, DE, ES, IT, NL, PT)

LibreOffice pour la conversion des formats Office

Les modèles de TAL spaCy préinstallés

Un utilisateur non root, des vérifications de santé, un volume de données persistant

6. Le workflow de l'API

Le workflow standard de traitement 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 workflow (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 codes 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 ne quitte votre machine.

Modules de modèles

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

8. Expressions personnalisées

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

Le workflow de relecture : API → application de bureau

📂

Détection par lots

API ou CLI

📦

Bundle .psreview

document + annotations

🖥️

Relecture sur 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 le bundle de relecture

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

POST

/api/documents/import-review

Importer le bundle de relecture

Étape 2 — Importer dans l'application de bureau

Étape 3 — Relire, modifier et anonymiser

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 machine — 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 une fois en ligne, puis mise en cache localement pour un usage hors ligne (durée de vie de 35 jours)

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'installateur l'ajoute automatiquement.

La conversion des fichiers Office échoue

Installez LibreOffice. Le format DOCX dispose d'une solution de repli en pur Python, mais les formats XLSX/PPTX nécessitent LibreOffice.

« 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

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 pousser 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é

POST

/api/documents/batch-anonymize

Anonymiser en lot

Anonymisez plusieurs documents en une seule requête. Jusqu'à 50 documents traités en parallèle.

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 aux côtés 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": "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

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 machine ; aucune donnée n'en sort.

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

L'API auto-hébergée n'impose aucune limite de débit par défaut. Vous pouvez configurer une limitation de débit à l'aide de variables d'environnement, au besoin.