Developers
Referência da API

Documentação da API

Referência completa da API REST do mecanismo auto-hospedado do promptShield. Todos os endpoints estão disponíveis na URL da sua implantação.

URL base

http://localhost:8000

Substitua pelo host e pela porta da sua implantação.

Esquema OpenAPI

O servidor disponibiliza /docs (Swagger UI), /redoc e /openapi.json. No modo de chave de API, os três exigem o cabeçalho Authorization, por isso um navegador não consegue abri-los diretamente. Obtenha o esquema e carregue em qualquer cliente capaz de enviar um cabeçalho:

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

Um navegador não consegue enviar o cabeçalho Authorization em uma navegação, por isso /docs responde 401 no modo de chave de API. O esquema acima é o caminho que funciona.

Autenticação

Quando PROMPTSHIELD_API_KEY está definida (por promptshield serve --api-key ou pela variável de ambiente do Docker), cada requisição precisa enviá-la como Authorization: Bearer <api-key>; chaves ausentes ou erradas recebem 401, e uma chave com escopo limitado a algumas operações recebe 403 nas demais. O endpoint /health está sempre isento. Se nenhuma chave de API estiver definida, o servidor roda sem autenticação e aceita todas as requisições, o que só é adequado em uma rede local de confiança.

Início rápido

Coloque a API local para rodar com o Docker. O primeiro download ocupa cerca de 3,8 GB.

1

Obter sua chave de API

bash
export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

Sua chave de API está disponível no painel de chaves de API.

2

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

A imagem inclui o Tesseract OCR, o LibreOffice e os modelos de detecção de inglês e francês. Os outros idiomas são instalados com promptshield models install.

3

Confirmar que está funcionando

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

Processar seu primeiro 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

Prefere uma instalação local em Python?

O pacote Python ainda não está no PyPI, por isso pip install promptshield-app não vai funcionar. Use a imagem Docker acima ou compile a partir do código-fonte. Vamos atualizar esta página quando o pacote for publicado.

Guia passo a passo

Um passo a passo completo para configurar a API local e integrá-la ao seu fluxo de trabalho.

1. Pré-requisitos

Antes de começar, verifique se você tem o seguinte instalado:

Docker (a instalação suportada atualmente)
Python 3.11 ou mais recente
pip (incluído no Python)
Uma chave de API do promptShield (plano Pro)

Opcional (para suporte completo a formatos):

Tesseract OCR: para PDFs digitalizados/baseados em imagem
LibreOffice: não é necessário para .docx, .xlsx, .xls e .pptx, que são convertidos em Python

2. Instalar o SDK

Instale o pacote Python do promptShield. A instalação base trata arquivos PDF. Adicione o extra office para Word/Excel/PowerPoint.

O pacote Python ainda não foi publicado no PyPI, por isso os dois comandos abaixo não vão funcionar. Por enquanto, use a imagem Docker da seção 5. Todo o resto desta página vale para as duas formas.

Instalação base (apenas PDF)
bash
pip install promptshield-app
Com suporte a formatos do Office
bash
pip install "promptshield-app[office]"

Instale modelos de idioma (pacotes de entidades) pela 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 pacotes de idioma adicionais da mesma 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. Autenticação

A API local usa sua chave de API do promptShield para validar a licença. Defina a chave como variável de ambiente ou informe ao iniciar o 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"

A chave de API é validada online na inicialização e novamente a cada 6 horas. Cada resposta fica em cache localmente, e assim o servidor continua funcionando por até 3 dias se não conseguir contatar o servidor de licenças.

4. Iniciar o servidor da API

Inicie o servidor local com um único 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.

Opções disponíveis:

--hostEndereço de escuta (padrão: 127.0.0.1)
--portPorta de escuta (padrão: 8000)
--api-keyChave de API (alternativa à variável de ambiente)

Depois de iniciada, a API fica disponível na URL exibida. O esquema OpenAPI está em /openapi.json; envie sua chave de API também nessa requisição.

5. Implantação com Docker

Para implantações em produção, o Docker oferece uma experiência sem instalação, com todas as dependências incluídas.

Contêiner ú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
Com o 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:

Crie um arquivo .env com sua chave de API:

.env
bash
PROMPTSHIELD_API_KEY=ps_live_your_key_here

A imagem Docker inclui:

Tesseract OCR com 8 pacotes de idioma (EN, FR, DE, ES, IT, NL, PT, PL)
LibreOffice para a conversão de formatos do Office
Modelos spaCy de inglês e francês pré-instalados (outros idiomas via models install)
Usuário sem privilégios de root, verificações de integridade, volume de dados persistente

6. Fluxo de trabalho da API

O fluxo de trabalho padrão de processamento de documentos tem 5 passos:

1Upload. Envie seu documento para o servidor
2Detectar. Execute o pipeline de detecção de dados pessoais (padrões + entidades + LLM opcional)
3Revisar. Inspecione as regiões detectadas, edite ou confirme
4Anonimizar. Substitua os dados pessoais por códigos
5Baixar. Obtenha o documento anonimizado

Exemplo de fluxo de trabalho 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 da CLI

Processe documentos direto na linha de comando, sem iniciar um servidor:

Detectar dados pessoais e salvar um relatório 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 um documento em um único passo
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 os códigos em um documento anonimizado anteriormente
bash
promptshield detokenize contract-safe.pdf -o contract-restored.pdf
# Restored 42 tokens, saved to contract-restored.pdf

Todos os comandos da CLI validam sua chave de API e processam os documentos localmente. Nenhum dado dos documentos sai do seu dispositivo.

Extras de modelos

Use o comando models integrado para procurar, instalar e remover pacotes de idioma de entidades. Defina PROMPTSHIELD_ASSETS_DIR para que a CLI e o servidor em execução os encontrem.

Defina o diretório de instalação uma vez (adicione ao perfil do seu shell):
bash
export PROMPTSHIELD_ASSETS_DIR="$HOME/.local/share/promptshield/assets"
# Windows: $env:PROMPTSHIELD_ASSETS_DIR = "$env:APPDATA\promptshield\assets"
Procurar pacotes disponíveis com o status de instalação
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)  ...
Baixar e instalar um pacote (sem precisar de 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 os pacotes instalados em PROMPTSHIELD_ASSETS_DIR
bash
promptshield models installed
# Installed models:
#   spacy-en-md   English (medium)
#   spacy-fr-md   French (medium)
Remover um pacote
bash
promptshield models remove spacy-fr-md

Os pacotes instalados são reconhecidos automaticamente pelo detect, pelo anonymize e pelo servidor da API em execução. O comando install se comunica diretamente com o servidor de licenças: não é preciso nenhum sidecar em execução.

8. Expressões personalizadas

Os padrões e as entidades integrados cobrem a maioria dos dados pessoais, mas cada organização tem seus próprios identificadores: números de contrato, códigos internos de projeto, números fiscais, marcações de confidencialidade. Adicione esses identificadores como expressões e eles passam a ser tratados como dados pessoais plenos, sinalizados com o tipo CUSTOM, com caixa delimitadora completa + propagação entre páginas. Disponível na CLI (-e / --expression), na API HTTP auto-hospedada (blacklist_terms) e pelas predefinições de demo/setup.json.

CLI: flag -e / --expression repetível
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: corpo 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.
Arquivo de predefinições: aplicado em cada chamada --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 o nome: expressions agora é o nome canônico nas três superfícies: CLI (-e / --expression), API HTTP (expressions / expressions_action / expressions_fuzziness) e o rótulo na interface do aplicativo para computador. As chaves anteriores blacklist_terms / blacklist_action / blacklist_fuzziness da API HTTP continuam funcionando por meio de um alias do Pydantic, para manter a retrocompatibilidade, de modo que as integrações existentes não quebram.

Fluxo de revisão: API → Aplicativo para computador

A detecção automática em escala é só metade da história: ela nunca atinge 100% de precisão, e sempre há falsos positivos para dispensar e entidades faltando para acrescentar. O promptShield fecha o ciclo com um pacote .psreview portátil: detecte de forma programática, importe no aplicativo para computador para um controle de qualidade visual feito por uma pessoa e depois anonimize.

📂
Detecção em lote
API ou CLI
📦
Pacote .psreview
documento + anotações
🖥️
Revisão no computador
dispensar falsos positivos · adicionar dados pessoais ausentes
✅
PDFs anonimizados

Passo 1a: detectar e exportar (CLI, em um só 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))

Passo 1b: detectar e 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 pacote de revisão

Baixa o documento e todas as anotações de regiões como um pacote .psreview (ZIP portátil).

POST
/api/documents/import-review

Importar pacote de revisão

Envie um pacote .psreview. Extrai o documento (executa OCR), injeta as anotações de regiões salvas e abre o documento no status REVIEWING, pronto para o controle de qualidade visual, sem executar a detecção novamente.

Passo 2: revisar, editar e anonimizar

Use a barra lateral de regiões para dispensar os falsos positivos (defina a ação como Cancelar), desenhe novas regiões para o que o modelo tiver deixado passar e depois clique em Transferir. O aplicativo para computador executa a anonimização e salva o PDF anonimizado na sua pasta Downloads.

8. SDK de Python (importação direta)

Para integrações avançadas, importe os módulos principais diretamente no seu código Python. Isso dá a você controle total sobre cada passo do processamento.

Exemplo completo em 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

Exemplo de processamento em lote

Processar vários arquivos em um diretório:

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. Segurança e privacidade dos dados

O promptShield foi projetado para ambientes de confiança zero:

Todo o processamento acontece localmente: nenhum conteúdo de documento jamais é enviado para servidores externos
O registro de códigos fica no seu dispositivo, o mesmo perímetro de confiança dos seus documentos de origem, e nunca é enviado
A autenticação por chave de API impede o acesso não autorizado no modo auto-hospedado
O Docker roda como usuário sem privilégios de root, com privilégios mínimos
A chave de API é validada online na inicialização e a cada 6 horas, e fica em cache localmente (máximo de 3 dias offline)

10. Resolução de problemas

Problemas comuns e soluções:

Erro 'No spaCy model found' ou 'no NER model loaded'

Defina PROMPTSHIELD_ASSETS_DIR e instale um pacote: promptshield models install spacy-en-md. Como alternativa, para uma instalação em todo o sistema: python -m spacy download en_core_web_sm

O OCR não funciona em PDFs digitalizados

Instale o Tesseract OCR e verifique se ele está no seu PATH. No Windows, o instalador o adiciona automaticamente.

Os arquivos do Office não são convertidos

Arquivos do Word, Excel e PowerPoint (.docx, .xlsx, .xls, .pptx) são convertidos em Python, sem LibreOffice. Verifique se o extra office está instalado e se o arquivo não está protegido por senha.

'Invalid API key' na inicialização

Verifique se sua chave começa com ps_live_ e se sua assinatura está ativa. As chaves podem ser gerenciadas em /developers/api-keys.

Documentos

POST
/api/documents/upload

Enviar documento

Envie um documento para processamento. Aceita arquivos PDF, DOCX, XLSX, PPTX e de imagem.

GET
/api/documents

Listar documentos

Retorna todos os documentos enviados, com o status de detecção e anonimização.

GET
/api/documents/{id}

Obter documento

Retorna informações detalhadas sobre um documento específico, incluindo o número de páginas e o status da detecção.

DELETE
/api/documents/{id}

Excluir documento

Remove um documento e todos os dados associados do servidor.

Detecção

POST
/api/documents/{id}/detect

Detectar dados pessoais

Executa o pipeline de detecção de dados pessoais em um documento. Aceita um corpo JSON opcional para substituir as configurações de detecção (confidence_threshold, regex_enabled, ner_enabled, regex_types etc.) apenas nesta execução.

POST
/api/documents/{id}/redetect

Detectar dados pessoais novamente

Executa a detecção novamente com controle total dos parâmetros. Aceita confidence_threshold, regex_types, ner_types, blacklist_terms e mais.

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

Progresso da detecção

Retorna o progresso de uma tarefa de detecção em andamento (porcentagem, página atual e status).

GET
/api/documents/{id}/regions

Obter regiões

Retorna todas as regiões de dados pessoais detectadas em um documento, com tipo, texto, pontuação de confiança e caixa delimitadora.

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

Atualizar regiões em lote

Define a ação (TOKENIZE, REMOVE ou CANCEL) para várias regiões de uma só vez, filtradas por tipo de entidade.

Anonimizar e exportar

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

Sincronizar regiões

Substitui toda a lista de regiões de um documento. Use depois de editar as regiões no lado do cliente para enviar as alterações antes de anonimizar.

POST
/api/documents/{id}/anonymize

Anonimizar documento

Anonimiza um documento substituindo os dados pessoais detectados por códigos. Retorna o documento processado.

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

Baixar documento anonimizado

Baixa o resultado anonimizado. {type} é 'pdf' ou 'text'. O resultado sempre sai em PDF (entradas que não são PDF são convertidas), por isso 'pdf' é o formato principal.

POST
/api/documents/batch-anonymize

Anonimizar em lote

Anonimiza vários documentos em uma única requisição: até 50 por requisição, processados 3 de cada vez.

Decodificar

POST
/api/detokenize

Decodificar texto

Substitui os códigos em uma string de texto pelos valores originais do cofre.

POST
/api/detokenize/file

Decodificar arquivo

Envie um documento codificado e receba uma versão com todos os códigos substituídos pelos valores originais.

Cofre e registro de códigos

GET
/api/vault/status

Status do cofre

Retorna as estatísticas do cofre: total de códigos, total de documentos, tamanho do registro.

GET
/api/vault/tokens

Listar códigos

Retorna todas as correspondências entre código e original armazenadas no cofre.

POST
/api/vault/export

Exportar cofre

Exporta todo o cofre como arquivo JSON para backup ou migração.

POST
/api/vault/import

Importar cofre

Importa um JSON de cofre exportado anteriormente para restaurar as correspondências de códigos.

Integridade

GET
/health

Verificação de integridade

Retorna o status de integridade do servidor. Use para monitoramento e sondas de integridade do balanceador de carga.

Configurações

GET
/api/settings

Obter configurações

Retorna a configuração atual de detecção e processamento (limiares, pipelines ativados, idioma etc.).

PATCH
/api/settings

Atualizar configurações

Atualiza parcialmente as configurações globais de detecção. As alterações valem para todas as detecções seguintes.

GET
/api/settings/patterns

Listar padrões personalizados

Retorna todos os padrões definidos pelo usuário usados na detecção personalizada de dados pessoais.

POST
/api/settings/patterns

Criar padrão personalizado

Adiciona um novo padrão personalizado à detecção de dados pessoais. Os padrões são avaliados junto com as regras integradas.

Exemplo

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

A classe PromptShield executa todo o pipeline localmente: detectar, anonimizar e decodificar em três chamadas. Todo o processamento acontece no seu dispositivo; nenhum dado dos documentos sai dele.

O SDK é distribuído com o pacote Python, que ainda não está no PyPI. Até lá, os endpoints HTTP acima fazem o mesmo trabalho.

Python SDK
bash
from promptshield import PromptShield

ps = PromptShield()

# Detectar dados pessoais
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 (tokenização reversível)
out = ps.anonymize("contract.pdf", "contract-safe.pdf")
print(f"Done: {out.tokens_created} tokens created")

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

Tratamento de erros

Todas as respostas de erro seguem um formato JSON padrão, com um campo detail que descreve o erro.

400

Requisição inválida. Parâmetros incorretos ou arquivo corrompido / não suportado.

401

Não autorizado. Chave de API ausente ou inválida (Authorization: Bearer) no modo de chave de API.

403

Proibido. A chave de API não tem o escopo necessário (detect / anonymize / detokenize).

404

Não encontrado. O ID do documento não existe.

422

Não processável. Falta um campo obrigatório ou o arquivo está protegido por senha.

500

Erro do servidor. Consulte os logs do servidor para mais detalhes.

503

Um modelo de detecção necessário não está instalado. Instale com promptshield models install.

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

Limites de taxa

Por padrão, a API auto-hospedada aceita até 6.000 requisições por minuto por IP de cliente. Para mudar esse limite, defina a variável de ambiente PROMPTSHIELD_SELF_HOSTED_RATE.