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.

Documentación interactiva de la API

Con el servidor en ejecución, visite /docs para acceder a una interfaz Swagger interactiva generada automáticamente donde puede probar cada endpoint directamente.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

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 obtienen un 401, y una clave limitada a solo algunas operaciones obtiene un 403 en el resto. 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 en menos de 5 minutos.

Instalar el paquete

bash

pip install promptshield-app

Instalar un modelo de idioma

bash

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

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

Iniciar el servidor

bash

promptshield serve --port 8000

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

O ejecútelo con Docker (sin instalación)

bash

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

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:

Python 3.11 o más reciente

pip (incluido con Python)

Una clave de API de promptShield (plan Basic o Pro)

Opcional. Para la compatibilidad completa con formatos:

Tesseract OCR. Para PDF escaneados o basados en imágenes

LibreOffice. Para la conversión de .docx, .xlsx, .pptx

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.

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 la validación de 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 luego se almacena en caché localmente durante hasta 35 días, de modo que el servidor puede ejecutarse totalmente sin conexión tras el primer arranque.

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

Opciones disponibles:

--host	Dirección de enlace (por defecto: 127.0.0.1)
--port	Puerto de enlace (por defecto: 8000)
--api-key	Clave de API (alternativa a la variable de entorno)

Una vez iniciado, la API está disponible en la URL que se muestra. La documentación interactiva de Swagger está en /docs.

5. Despliegue con Docker (alternativa)

Para los despliegues en producción, Docker ofrece una experiencia sin instalación con todas las dependencias 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 7 paquetes de idioma (EN, FR, DE, ES, IT, NL, PT)

LibreOffice para la conversión de formatos de Office

Modelos de PLN de spaCy preinstalados

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 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 las tres superficies: la CLI (-e / --expression), la API HTTP (expressions / expressions_action / expressions_fuzziness) y la etiqueta de la interfaz de escritorio. Las claves anteriores blacklist_terms / blacklist_action / blacklist_fuzziness de la API HTTP siguen funcionando mediante un alias de Pydantic por retrocompatibilidad, así que las integraciones existentes siguen funcionando.

Flujo de revisión: API → escritorio

La detección automática a escala es solo la mitad de la historia. La detección automática nunca alcanza una precisión del 100 %: siempre hay falsos positivos que descartar y entidades omitidas que añadir. promptShield cierra el círculo con un paquete .psreview portátil: detecte mediante programación, impórtelo en la aplicación de escritorio para una revisión visual humana y luego anonimice.

📂

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 — Importar en la aplicación de escritorio

Abra la aplicación de escritorio de promptShield. En la pantalla de subida, haga clic en Importar para revisar y seleccione el archivo .psreview. El documento se abre de inmediato en modo de revisión: todas las regiones detectadas vienen ya cargadas, sin necesidad de un paso de detección.

Paso 3 — 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 Exportar. La aplicación de escritorio ejecuta la anonimización y guarda el PDF ocultado 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 máquina, 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 una vez y luego se almacena en caché localmente para su uso sin conexión (TTL de 35 días)

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

Instale LibreOffice. DOCX tiene una alternativa en Python puro, pero XLSX/PPTX requieren LibreOffice.

'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 documentos procesados en paralelo.

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 reciba una versión con todos los códigos restaurados a 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 de salud 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": "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 de Python

La clase PromptShield ejecuta toda la canalización localmente: detectar, anonimizar y decodificar en tres llamadas. Todo el procesamiento ocurre en su máquina; ningún dato sale de ella.

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 (tokenizació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

La API autoalojada no tiene límites de frecuencia por defecto. Puede configurar la limitación de frecuencia mediante variables de entorno si lo necesita.

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.

Documentación interactiva de la API

Con el servidor en ejecución, visite /docs para acceder a una interfaz Swagger interactiva generada automáticamente donde puede probar cada endpoint directamente.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

Autenticación

Inicio rápido

Ponga en marcha la API local en menos de 5 minutos.

Instalar el paquete

bash

pip install promptshield-app

Instalar un modelo de idioma

bash

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

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

Iniciar el servidor

bash

promptshield serve --port 8000

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

O ejecútelo con Docker (sin instalación)

bash

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

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:

Python 3.11 o más reciente

pip (incluido con Python)

Una clave de API de promptShield (plan Basic o Pro)

Opcional. Para la compatibilidad completa con formatos:

Tesseract OCR. Para PDF escaneados o basados en imágenes

LibreOffice. Para la conversión de .docx, .xlsx, .pptx

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.

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 la validación de 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"

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

Opciones disponibles:

--host	Dirección de enlace (por defecto: 127.0.0.1)
--port	Puerto de enlace (por defecto: 8000)
--api-key	Clave de API (alternativa a la variable de entorno)

Una vez iniciado, la API está disponible en la URL que se muestra. La documentación interactiva de Swagger está en /docs.

5. Despliegue con Docker (alternativa)

Para los despliegues en producción, Docker ofrece una experiencia sin instalación con todas las dependencias 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 7 paquetes de idioma (EN, FR, DE, ES, IT, NL, PT)

LibreOffice para la conversión de formatos de Office

Modelos de PLN de spaCy preinstalados

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

8. Expresiones personalizadas

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

Flujo de revisión: API → escritorio

📂

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

Paso 2 — Importar en la aplicación de escritorio

Paso 3 — Revisar, editar y anonimizar

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 máquina, 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 una vez y luego se almacena en caché localmente para su uso sin conexión (TTL de 35 días)

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

Instale LibreOffice. DOCX tiene una alternativa en Python puro, pero XLSX/PPTX requieren LibreOffice.

'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

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 documentos procesados en paralelo.

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 reciba una versión con todos los códigos restaurados a 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 de salud 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": "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 de Python

La clase PromptShield ejecuta toda la canalización localmente: detectar, anonimizar y decodificar en tres llamadas. Todo el procesamiento ocurre en su máquina; ningún dato sale de ella.

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 (tokenizació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

La API autoalojada no tiene límites de frecuencia por defecto. Puede configurar la limitación de frecuencia mediante variables de entorno si lo necesita.