Developers
Referencia de la API

Documentación de la API

Referencia completa de la API REST del motor autoalojado de promptShield. Todos los endpoints están disponibles en la URL de su despliegue.

URL base

http://localhost:8000

Sustitúyala por el host y el puerto de su despliegue.

Esquema OpenAPI

El servidor expone /docs (Swagger UI), /redoc y /openapi.json. En modo de clave de API los tres exigen la cabecera Authorization, por lo que un navegador no puede abrirlos directamente. Descargue el esquema y cárguelo en cualquier cliente que pueda enviar una cabecera:

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

Un navegador no puede enviar la cabecera Authorization en una navegación, por lo que /docs responde 401 en modo de clave de API. La vía que funciona es el esquema de arriba.

Autenticación

Cuando PROMPTSHIELD_API_KEY está definida (mediante promptshield serve --api-key o la variable de entorno de Docker), cada solicitud debe incluirla como Authorization: Bearer <api-key>; las claves ausentes o incorrectas reciben un 401, y una clave limitada a ciertas operaciones recibe un 403 en las demás. El endpoint /health siempre está exento. Si no se define ninguna clave de API, el servidor se ejecuta sin autenticación y acepta todas las solicitudes: solo es adecuado en una red local de confianza.

Inicio rápido

Ponga en marcha la API local con Docker. La primera descarga ocupa unos 3,8 GB.

1

Obtener su clave de API

bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

Su clave de API está disponible en el panel de claves de API.

2

Iniciar el servidor

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

La imagen incluye Tesseract OCR, LibreOffice y los modelos de detección de inglés y francés. Instale los demás idiomas con promptshield models install.

3

Comprobar que está en marcha

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

Procesar su primer documento

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

¿Prefiere una instalación local de Python?

El paquete de Python aún no está en PyPI, por lo que pip install promptshield-app no funcionará. Utilice la imagen de Docker de arriba o compile desde el código fuente. Actualizaremos esta página cuando se publique el paquete.

Guía paso a paso

Un recorrido completo para configurar la API local e integrarla en su flujo de trabajo.

1. Requisitos previos

Antes de empezar, asegúrese de tener instalado lo siguiente:

Docker (la instalación admitida hoy)
Python 3.11 o más reciente
pip (incluido con Python)
Una clave de API de promptShield (plan Pro)

Opcional (para la compatibilidad completa con formatos):

Tesseract OCR: para PDF escaneados o basados en imágenes
LibreOffice: no hace falta para .docx, .xlsx, .xls ni .pptx, que se convierten en Python

2. Instalar el SDK

Instale el paquete de Python de promptShield. La instalación base gestiona los archivos PDF. Añada el extra office para Word/Excel/PowerPoint.

El paquete de Python aún no está publicado en PyPI, por lo que los dos comandos siguientes no funcionarán. Utilice por ahora la imagen de Docker de la sección 5. Todo lo demás de esta página vale para ambos casos.

Instalación base (solo PDF)
bash
pip install promptshield-app
Con compatibilidad con formatos de Office
bash
pip install "promptshield-app[office]"

Instale los modelos de idioma (paquetes de NER) mediante la 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

Instale paquetes de idioma adicionales de la misma forma:

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. Autenticación

La API local usa su clave de API de promptShield para validar la licencia. Establézcala como variable de entorno o pásela al iniciar el servidor.

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 clave de API se valida en línea al inicio y de nuevo cada 6 horas. Cada respuesta se guarda en caché localmente, de modo que el servidor sigue funcionando hasta 3 días si no puede contactar con el servidor de licencias.

4. Iniciar el servidor de la API

Inicie el servidor local con un solo comando:

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.

Opciones disponibles:

--hostDirección de escucha (por defecto: 127.0.0.1)
--portPuerto de escucha (por defecto: 8000)
--api-keyClave de API (alternativa a la variable de entorno)

Una vez iniciado, la API está disponible en la URL que se muestra. El esquema OpenAPI está en /openapi.json; envíe también su clave de API con esa solicitud.

5. Despliegue con Docker

Para desplegar en producción, Docker le ahorra la instalación: todas las dependencias vienen incluidas.

Contenedor único
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
Con 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:

Cree un archivo .env con su clave de API:

.env
bash
PROMPTSHIELD_API_KEY=ps_live_your_key_here

La imagen de Docker incluye:

Tesseract OCR con 8 paquetes de idioma (EN, FR, DE, ES, IT, NL, PT, PL)
LibreOffice para la conversión de formatos de Office
Modelos de spaCy para inglés y francés preinstalados (otros idiomas con models install)
Usuario sin privilegios de root, comprobaciones de estado, volumen de datos persistente

6. Flujo de trabajo de la API

El flujo estándar de procesamiento de documentos tiene 5 pasos:

1Subir. Envíe su documento al servidor
2Detectar. Ejecute la canalización de detección de datos personales (regex + NER + LLM opcional)
3Revisar. Inspeccione las regiones detectadas, edítelas o confírmelas
4Anonimizar. Sustituya los datos personales por códigos
5Descargar. Recupere el documento anonimizado

Ejemplo del flujo completo (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. Comandos de la CLI

Procese documentos directamente desde la línea de comandos sin iniciar un servidor:

Detectar datos personales y guardar un informe 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
Anonimizar un documento en un solo paso
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
Restaurar los códigos de un documento anonimizado previamente
bash
promptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdf

Todos los comandos de la CLI validan su clave de API y procesan los documentos localmente. Ningún dato de los documentos sale de su dispositivo.

Complementos de modelos

Use el comando integrado models para examinar, instalar y eliminar paquetes de idioma de NER. Defina PROMPTSHIELD_ASSETS_DIR para que tanto la CLI como el servidor en ejecución los encuentren.

Defina el directorio de instalación una vez (añádalo a su perfil de shell):
bash
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
Examinar los paquetes disponibles con su estado de instalación
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)  ...
Descargar e instalar un paquete (no se necesita servidor)
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
Listar los paquetes instalados en PROMPTSHIELD_ASSETS_DIR
bash
promptshield models installed
# Installed models:
#   spacy-en-md   English (medium)
#   spacy-fr-md   French (medium)
Eliminar un paquete
bash
promptshield models remove spacy-fr-md

Los paquetes instalados se detectan automáticamente en detect, anonymize y el servidor de la API en ejecución. El comando install se comunica directamente con el servidor de licencias: no se necesita ningún sidecar en ejecución.

8. Expresiones personalizadas

Las expresiones regulares y la detección de entidades integradas cubren la mayoría de los datos personales, pero cada organización tiene sus propios identificadores: números de contrato, códigos internos de proyecto, identificadores fiscales, indicadores de confidencialidad. Añádalos como expresiones y se tratarán como datos personales de pleno derecho, marcados con el tipo CUSTOM, con recuadro delimitador completo y propagación entre páginas. Disponible en la CLI (-e / --expression), en la API HTTP autoalojada (blacklist_terms) y mediante los preajustes de demo/setup.json.

CLI: opción repetible -e / --expression
bash
# Literal text — case-insensitive substring match
promptshield detect contract.pdf -e SA-2026-0847 -e "84-329-1057"

# Repeatable — pass as many -e flags as you need
promptshield detect contract.pdf \
  -e ACME-CONFIDENTIAL \
  -e "Internal Use Only" \
  -e CUST-12345

# Regex — prefix with "re:" for full regex semantics
promptshield detect contract.pdf \
  -e "re:CASE-\d{4}-[A-Z]{3}" \
  -e "re:Project [A-Z][a-z]+"
API HTTP: cuerpo 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.
Archivo de preajustes: se aplica en cada llamada --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

Sobre el nombre: expressions es ahora el nombre canónico en los tres puntos: la CLI (-e / --expression), la API HTTP (expressions / expressions_action / expressions_fuzziness) y la etiqueta de la interfaz de escritorio. Por retrocompatibilidad, las claves anteriores blacklist_terms / blacklist_action / blacklist_fuzziness de la API HTTP se siguen aceptando mediante un alias de Pydantic, de modo que las integraciones existentes no se rompen.

Flujo de revisión: API → escritorio

Detectar automáticamente a gran escala solo resuelve la mitad del trabajo, porque ninguna detección automática alcanza una precisión del 100 %: siempre quedan falsos positivos que descartar y entidades omitidas que añadir. promptShield completa el proceso con un paquete .psreview portátil: detecte mediante programación, importe el paquete en la aplicación de escritorio para que una persona lo revise visualmente y anonimice después.

📂
Detección por lotes
API o CLI
📦
Paquete .psreview
documento + anotaciones
🖥️
Revisión de escritorio
descartar falsos positivos · añadir datos personales omitidos
✅
PDF anonimizados

Paso 1a: detectar y exportar (CLI, en un solo comando)

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

Paso 1b: detectar y exportar (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

Exportar el paquete de revisión

Descargue el documento y todas sus anotaciones de regiones como un paquete ZIP .psreview portátil.

POST
/api/documents/import-review

Importar el paquete de revisión

Suba un paquete .psreview. Extrae el documento (ejecuta el OCR), inyecta las anotaciones de regiones guardadas y abre el documento en estado REVIEWING: listo para la revisión visual sin volver a ejecutar la detección.

Paso 2: revisar, editar y anonimizar

Use la barra lateral de regiones para descartar los falsos positivos (asigne la acción Cancelar), dibuje nuevas regiones para lo que el modelo haya omitido y luego haga clic en Descargar. La aplicación de escritorio ejecuta la anonimización y guarda el PDF tachado en su carpeta de Descargas.

8. SDK de Python (importación directa)

Para integraciones avanzadas, importe los módulos principales directamente en su código de Python. Esto le da control total sobre cada paso del procesamiento.

Ejemplo completo en Python
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

Ejemplo de procesamiento por lotes

Procesar varios archivos de un directorio:

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. Seguridad y privacidad de los datos

promptShield está diseñado para entornos de confianza cero:

Todo el procesamiento ocurre localmente. Ningún contenido de los documentos se envía nunca a servidores externos
El registro de códigos permanece en su dispositivo, dentro del mismo perímetro de confianza que sus documentos de origen, y nunca se sube
La autenticación por clave de API evita el acceso no autorizado en el modo autoalojado
Docker se ejecuta como usuario sin privilegios de root y con privilegios mínimos
La clave de API se valida en línea al inicio y cada 6 horas, y se guarda en caché localmente (máximo 3 días sin conexión)

10. Resolución de problemas

Problemas habituales y soluciones:

Error 'No spaCy model found' o 'no NER model loaded'

Defina PROMPTSHIELD_ASSETS_DIR e instale un paquete: promptshield models install spacy-en-md. Como alternativa, para una instalación en todo el sistema: python -m spacy download en_core_web_sm

El OCR no funciona en los PDF escaneados

Instale Tesseract OCR y asegúrese de que está en su PATH. En Windows, el instalador lo añade automáticamente.

Los archivos de Office no se convierten

Los archivos de Word, Excel y PowerPoint (.docx, .xlsx, .xls, .pptx) se convierten en Python, sin LibreOffice. Compruebe que el extra office está instalado y que el archivo no está protegido con contraseña.

'Invalid API key' al iniciar

Compruebe que su clave empieza por ps_live_ y que su suscripción está activa. Las claves se gestionan en /developers/api-keys.

Documentos

POST
/api/documents/upload

Subir documento

Suba un documento para procesarlo. Admite archivos PDF, DOCX, XLSX, PPTX e imágenes.

GET
/api/documents

Listar documentos

Recupere todos los documentos subidos con su estado de detección y anonimización.

GET
/api/documents/{id}

Obtener documento

Obtenga información detallada de un documento concreto, incluidos el número de páginas y el estado de detección.

DELETE
/api/documents/{id}

Eliminar documento

Elimine un documento y todos los datos asociados del servidor.

Detección

POST
/api/documents/{id}/detect

Detectar datos personales

Ejecute la canalización de detección de datos personales sobre un documento. Acepta un cuerpo JSON opcional para anular los ajustes de detección (confidence_threshold, regex_enabled, ner_enabled, regex_types, etc.) solo para esta ejecución.

POST
/api/documents/{id}/redetect

Volver a detectar datos personales

Vuelva a ejecutar la detección con control total de los parámetros. Acepta confidence_threshold, regex_types, ner_types, blacklist_terms y más.

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

Progreso de la detección

Obtenga el progreso de una tarea de detección en curso (porcentaje, página actual y estado).

GET
/api/documents/{id}/regions

Obtener regiones

Recupere todas las regiones de datos personales detectadas en un documento, con su tipo, texto, puntuación de confianza y recuadro delimitador.

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

Actualizar regiones en lote

Establezca la acción (TOKENIZE, REMOVE o CANCEL) para varias regiones a la vez, filtradas por tipo de entidad.

Anonimizar y exportar

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

Sincronizar regiones

Sustituya por completo la lista de regiones de un documento. Úselo tras editar las regiones en el cliente para enviar los cambios antes de anonimizar.

POST
/api/documents/{id}/anonymize

Anonimizar documento

Anonimice un documento sustituyendo los datos personales detectados por códigos. Devuelve el documento procesado.

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

Descargar el documento anonimizado

Descargue la salida anonimizada. {type} es 'pdf' o 'text'. La salida siempre se renderiza como PDF (las entradas que no son PDF se convierten), así que 'pdf' es el formato principal.

POST
/api/documents/batch-anonymize

Anonimizar en lote

Anonimice varios documentos en una sola solicitud: hasta 50 por solicitud, procesados de 3 en 3.

Decodificar

POST
/api/detokenize

Decodificar texto

Sustituya los códigos de una cadena de texto por sus valores originales del almacén.

POST
/api/detokenize/file

Decodificar archivo

Suba un documento codificado y recíbalo con todos los códigos sustituidos por sus valores originales.

Almacén y registro de códigos

GET
/api/vault/status

Estado del almacén

Obtenga las estadísticas del almacén: total de códigos, total de documentos, tamaño del registro.

GET
/api/vault/tokens

Listar códigos

Recupere todas las correspondencias de código a original almacenadas en el almacén.

POST
/api/vault/export

Exportar el almacén

Exporte todo el almacén como archivo JSON para hacer copia de seguridad o migrarlo.

POST
/api/vault/import

Importar el almacén

Importe un JSON de almacén exportado previamente para restaurar las correspondencias de códigos.

Estado

GET
/health

Comprobación de estado

Devuelve el estado del servidor. Úselo para la supervisión y las sondas de estado del balanceador de carga.

Ajustes

GET
/api/settings

Obtener ajustes

Recupere la configuración actual de detección y procesamiento (umbrales, canalizaciones activadas, idioma, etc.).

PATCH
/api/settings

Actualizar ajustes

Actualice parcialmente los ajustes globales de detección. Los cambios se aplican a todas las detecciones posteriores.

GET
/api/settings/patterns

Listar patrones personalizados

Obtenga todos los patrones de expresiones regulares definidos por el usuario para la detección personalizada de datos personales.

POST
/api/settings/patterns

Crear patrón personalizado

Añada un nuevo patrón de expresión regular para la detección de datos personales. Los patrones se evalúan junto con las reglas integradas.

Ejemplo

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

La clase PromptShield ejecuta toda la canalización localmente: detectar, anonimizar y decodificar en tres llamadas. Todo el procesamiento ocurre en su dispositivo; ningún dato de los documentos sale de él.

El SDK se distribuye con el paquete de Python, que aún no está en PyPI. Hasta entonces, los endpoints HTTP de arriba hacen el mismo trabajo.

Python SDK
bash
from promptshield import PromptShield

ps = PromptShield()

# Detectar datos personales
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']}")

# Anonimizar (codificación reversible)
out = ps.anonymize("contract.pdf", "contract-safe.pdf")
print(f"Done: {out.tokens_created} tokens created")

# Restaurar los valores originales
restored = ps.detokenize("contract-safe.pdf", "contract-restored.pdf")
print(f"Restored {restored.tokens_replaced} tokens")

Gestión de errores

Todas las respuestas de error siguen un formato JSON estándar con un campo detail que describe el error.

400

Solicitud incorrecta. Parámetros no válidos o un archivo dañado o no compatible.

401

No autorizado. Clave de API ausente o no válida (Authorization: Bearer) en el modo de clave de API.

403

Prohibido. La clave de API no tiene el alcance necesario (detect / anonymize / detokenize).

404

No encontrado. El ID del documento no existe.

422

No procesable. Falta un campo obligatorio o el archivo está protegido con contraseña.

500

Error del servidor. Consulte los registros del servidor para más detalles.

503

Un modelo de detección necesario no está instalado. Instálelo con promptshield models install.

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

Límites de frecuencia

Por defecto, la API autoalojada acepta hasta 6000 solicitudes por minuto por IP de cliente. Para cambiar ese límite, defina la variable de entorno PROMPTSHIELD_SELF_HOSTED_RATE.