Referência da API

Documentação da API

Referência completa da API REST para o motor auto-alojado do promptShield. Todos os endpoints estão disponíveis na URL da sua implementação.

URL base

http://localhost:8000

Substitua pelo anfitrião e porta da sua implementação.

Documentação interativa da API

Com o servidor em execução, visite /docs para uma interface Swagger interativa gerada automaticamente, onde pode testar cada endpoint diretamente.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

Autenticação

Quando PROMPTSHIELD_API_KEY está definida (via promptshield serve --api-key ou a variável de ambiente do Docker), cada pedido tem de a transportar como Authorization: Bearer <api-key>; chaves em falta ou erradas recebem 401, e uma chave com âmbito limitado a algumas operações recebe 403 nas restantes. O endpoint /health está sempre isento. Se não estiver definida nenhuma chave de API, o servidor corre sem autenticação e aceita todos os pedidos — adequado apenas numa rede local de confiança.

Início rápido

Ponha a API local a funcionar em menos de 5 minutos.

Instalar o pacote

bash

pip install promptshield-app

Instalar um modelo de idioma

bash

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

Definir a sua chave de API

bash

export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

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

Iniciar o servidor

bash

promptshield serve --port 8000

Processar o 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": "REVIEWING"}

curl -X POST http://localhost:8000/api/documents/abc123/detect \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"confidence_threshold": 0.7}'
# → {"doc_id": "abc123", "total_regions": 42, "regions": [...]}

curl -X POST http://localhost:8000/api/documents/abc123/anonymize \
  -H "$AUTH"
# → {"doc_id": "abc123", "tokens_created": 42, "regions_removed": 0, "output_path": "..."}

curl -o contract-safe.pdf \
  -H "$AUTH" \
  http://localhost:8000/api/documents/abc123/download/pdf

Ou execute com o Docker (sem instalação)

bash

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

Guia passo a passo

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

1. Pré-requisitos

Antes de começar, certifique-se de que tem o seguinte instalado:

Python 3.11 ou mais recente

pip (incluído no Python)

Uma chave de API do promptShield (plano Basic ou Pro)

Opcional. para suporte completo de formatos:

Tesseract OCR. para PDF digitalizados/baseados em imagem

LibreOffice. para a conversão de .docx, .xlsx, .pptx

2. Instalar o SDK

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

Instalação base (apenas PDF)

bash

pip install promptshield-app

Com suporte para formatos do Office

bash

pip install "promptshield-app[office]"

Instale modelos de idioma (pacotes de entidades) através da 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 a sua chave de API do promptShield para a validação de licença. Defina-a como variável de ambiente ou passe-a 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 no arranque e depois colocada em cache localmente durante 35 dias, para que o servidor possa funcionar totalmente offline após o primeiro arranque.

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

Opções disponíveis:

--host	Endereço de ligação (predefinição: 127.0.0.1)
--port	Porta de ligação (predefinição: 8000)
--api-key	Chave de API (alternativa à variável de ambiente)

Depois de iniciado, a API fica disponível na URL apresentada. A documentação Swagger interativa está em /docs.

5. Implementação com Docker (alternativa)

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

Contentor ú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 ficheiro .env com a sua chave de API:

.env

bash

PROMPTSHIELD_API_KEY=ps_live_your_key_here

A imagem Docker inclui:

Tesseract OCR com 7 pacotes de idioma (EN, FR, DE, ES, IT, NL, PT)

LibreOffice para a conversão de formatos do Office

Modelos de NLP do spaCy pré-instalados

Utilizador sem privilégios de root, verificações de estado, volume de dados persistente

6. Fluxo de trabalho da API

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

1Carregar. Envie o seu documento para o servidor

2Detetar. Execute o pipeline de deteção de dados pessoais (padrões + entidades + LLM opcional)

3Rever. Inspecione as regiões detetadas, edite ou confirme

4Anonimizar. Substitua os dados pessoais por códigos

5Transferir. 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 diretamente a partir da linha de comandos, sem iniciar um servidor:

Detetar dados pessoais e guardar 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 num ú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 num 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 a sua chave de API e processam os documentos localmente. Nenhum dado 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 da sua 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 estado 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)  ...

Transferir e instalar um pacote (sem necessidade 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 automaticamente reconhecidos pelo detect, anonymize e pelo servidor da API em execução. O comando install comunica diretamente com o servidor de licenças — não é necessário qualquer 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 os seus próprios identificadores — números de contrato, códigos de projeto internos, números fiscais, indicadores de confidencialidade. Adicione-os como expressões e passam a ser tratados como dados pessoais de pleno direito, assinalados com o tipo CUSTOM, com caixa delimitadora completa + propagação entre páginas. Disponível na CLI (-e / --expression), na API HTTP auto-alojada (blacklist_terms) e através das 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.

Ficheiro 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 de ambiente de trabalho. As chaves anteriores blacklist_terms / blacklist_action / blacklist_fuzziness na API HTTP continuam a funcionar através de um alias do Pydantic para retrocompatibilidade, pelo que as integrações existentes continuam a funcionar.

Fluxo de revisão: API → Ambiente de trabalho

A deteção automática em escala é apenas metade da história. A deteção automática nunca atinge 100% de precisão — há sempre falsos positivos para dispensar e entidades em falta para acrescentar. O promptShield fecha o ciclo com um pacote .psreview portátil: detete de forma programática, importe para a aplicação de ambiente de trabalho para um controlo de qualidade visual e humano e depois anonimize.

📂

Deteção em lote

API ou CLI

📦

Pacote .psreview

documento + anotações

🖥️

Revisão no ambiente de trabalho

dispensar falsos positivos · adicionar dados pessoais em falta

✅

PDF anonimizados

Passo 1a — Detetar e exportar (CLI, num 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 — Detetar 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

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

POST

/api/documents/import-review

Importar pacote de revisão

Carregue um pacote .psreview. Extrai o documento (executa OCR), injeta as anotações de regiões guardadas e abre o documento no estado REVIEWING — pronto para o controlo de qualidade visual, sem voltar a executar a deteção.

Passo 2 — Importar para a aplicação de ambiente de trabalho

Abra a aplicação de ambiente de trabalho do promptShield. No ecrã de carregamento, clique em Importar para revisão e selecione o ficheiro .psreview. O documento abre imediatamente em modo de revisão — todas as regiões detetadas estão pré-preenchidas, sem necessidade de um passo de deteção.

Passo 3 — Rever, 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 qualquer coisa que o modelo tenha deixado escapar e depois clique em Exportar. A aplicação de ambiente de trabalho executa a anonimização e guarda o PDF ocultado na sua pasta Transferências.

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

Para integrações avançadas, importe os módulos principais diretamente no seu código de Python. Isto dá-lhe controlo 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 ficheiros num 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 concebido para ambientes de confiança zero:

Todo o processamento acontece localmente. nenhum conteúdo de documento é alguma vez enviado para servidores externos

O registo de códigos permanece no seu dispositivo — o mesmo perímetro de confiança que os seus documentos de origem, nunca é carregado

A autenticação por chave de API impede o acesso não autorizado no modo auto-alojado

O Docker corre como utilizador sem privilégios de root, com privilégios mínimos

A chave de API é validada online uma vez e depois colocada em cache localmente para uso offline (TTL de 35 dias)

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. Em alternativa, para uma instalação a nível do sistema: python -m spacy download en_core_web_sm

O OCR não funciona em PDF digitalizados

Instale o Tesseract OCR e certifique-se de que está no seu PATH. No Windows, o instalador adiciona-o automaticamente.

Os ficheiros do Office não convertem

Instale o LibreOffice. O DOCX tem uma alternativa em Python puro, mas o XLSX/PPTX requerem o LibreOffice.

'Invalid API key' no arranque

Verifique que a sua chave começa por ps_live_ e que a sua subscrição está ativa. As chaves podem ser geridas em /developers/api-keys.

Documentos

POST

/api/documents/upload

Carregar documento

Carregue um documento para processamento. Suporta ficheiros PDF, DOCX, XLSX, PPTX e de imagem.

GET

/api/documents

Listar documentos

Obtenha todos os documentos carregados com o seu estado de deteção e anonimização.

GET

/api/documents/{id}

Obter documento

Obtenha informação detalhada sobre um documento específico, incluindo o número de páginas e o estado da deteção.

DELETE

/api/documents/{id}

Eliminar documento

Remova um documento e todos os dados associados do servidor.

Deteção

POST

/api/documents/{id}/detect

Detetar dados pessoais

Execute o pipeline de deteção de dados pessoais num documento. Aceita um corpo JSON opcional para substituir as definições de deteção (confidence_threshold, regex_enabled, ner_enabled, regex_types, etc.) apenas para esta execução.

POST

/api/documents/{id}/redetect

Voltar a detetar dados pessoais

Volte a executar a deteção com controlo total dos parâmetros. Aceita confidence_threshold, regex_types, ner_types, blacklist_terms e mais.

GET

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

Progresso da deteção

Obtenha o progresso de uma tarefa de deteção em curso (percentagem, página atual e estado).

GET

/api/documents/{id}/regions

Obter regiões

Obtenha todas as regiões de dados pessoais detetadas para 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

Defina 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

Substitua totalmente a lista de regiões de um documento. Use após editar as regiões do lado do cliente para enviar as alterações antes de anonimizar.

POST

/api/documents/{id}/anonymize

Anonimizar documento

Anonimize um documento substituindo os dados pessoais detetados por códigos. Devolve o documento processado.

GET

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

Transferir documento anonimizado

Transfira o resultado anonimizado. {type} é 'pdf' ou 'text'. O resultado é sempre apresentado em PDF (as entradas não-PDF são convertidas), pelo que 'pdf' é o formato principal.

POST

/api/documents/batch-anonymize

Anonimizar em lote

Anonimize vários documentos num único pedido. Até 50 documentos processados em simultâneo.

Descodificar

POST

/api/detokenize

Descodificar texto

Substitua os códigos numa cadeia de texto pelos seus valores originais do cofre.

POST

/api/detokenize/file

Descodificar ficheiro

Carregue um documento codificado e receba uma versão com todos os códigos restaurados nos valores originais.

Cofre e registo de códigos

GET

/api/vault/status

Estado do cofre

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

GET

/api/vault/tokens

Listar códigos

Obtenha todas as correspondências código-original armazenadas no cofre.

POST

/api/vault/export

Exportar cofre

Exporte todo o cofre como ficheiro JSON para cópia de segurança ou migração.

POST

/api/vault/import

Importar cofre

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

Estado

GET

/health

Verificação de estado

Devolve o estado de saúde do servidor. Use para monitorização e sondas de estado do balanceador de carga.

Definições

GET

/api/settings

Obter definições

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

PATCH

/api/settings

Atualizar definições

Atualize parcialmente as definições globais de deteção. As alterações aplicam-se a todas as deteções subsequentes.

GET

/api/settings/patterns

Listar padrões personalizados

Obtenha todos os padrões definidos pelo utilizador usados para a deteção personalizada de dados pessoais.

POST

/api/settings/patterns

Criar padrão personalizado

Adicione um novo padrão personalizado para a deteção de dados pessoais. Os padrões são avaliados em conjunto 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": "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

A classe PromptShield executa todo o pipeline localmente — detetar, anonimizar e descodificar em três chamadas. Todo o processamento acontece no seu dispositivo; nenhum dado sai dele.

Python SDK

bash

from promptshield import PromptShield

ps = PromptShield()

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

Pedido inválido. Parâmetros incorretos ou ficheiro corrompido / não suportado.

401

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

403

Proibido. A chave de API não tem o âmbito 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 ficheiro está protegido por palavra-passe.

500

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

503

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

Error Response Format

bash

{
  "detail": "Document not found: abc123"
}

Limites de taxa

A API auto-alojada não tem limites de taxa por predefinição. Pode configurar a limitação de taxa através de variáveis de ambiente, se necessário.

Developers

Referência da API

Documentação da API

Referência completa da API REST para o motor auto-alojado do promptShield. Todos os endpoints estão disponíveis na URL da sua implementação.

URL base

http://localhost:8000

Substitua pelo anfitrião e porta da sua implementação.

Documentação interativa da API

Com o servidor em execução, visite /docs para uma interface Swagger interativa gerada automaticamente, onde pode testar cada endpoint diretamente.

PROMPTSHIELD_DEBUG_API_DOCS=1 promptshield serve

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

Autenticação

Início rápido

Ponha a API local a funcionar em menos de 5 minutos.

Instalar o pacote

bash

pip install promptshield-app

Instalar um modelo de idioma

bash

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

Definir a sua chave de API

bash

export PROMPTSHIELD_API_KEY="ps_live_your_key_here"

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

Iniciar o servidor

bash

promptshield serve --port 8000

Processar o 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": "REVIEWING"}

curl -X POST http://localhost:8000/api/documents/abc123/detect \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"confidence_threshold": 0.7}'
# → {"doc_id": "abc123", "total_regions": 42, "regions": [...]}

curl -X POST http://localhost:8000/api/documents/abc123/anonymize \
  -H "$AUTH"
# → {"doc_id": "abc123", "tokens_created": 42, "regions_removed": 0, "output_path": "..."}

curl -o contract-safe.pdf \
  -H "$AUTH" \
  http://localhost:8000/api/documents/abc123/download/pdf

Ou execute com o Docker (sem instalação)

bash

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

Guia passo a passo

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

1. Pré-requisitos

Antes de começar, certifique-se de que tem o seguinte instalado:

Python 3.11 ou mais recente

pip (incluído no Python)

Uma chave de API do promptShield (plano Basic ou Pro)

Opcional. para suporte completo de formatos:

Tesseract OCR. para PDF digitalizados/baseados em imagem

LibreOffice. para a conversão de .docx, .xlsx, .pptx

2. Instalar o SDK

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

Instalação base (apenas PDF)

bash

pip install promptshield-app

Com suporte para formatos do Office

bash

pip install "promptshield-app[office]"

Instale modelos de idioma (pacotes de entidades) através da 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 a sua chave de API do promptShield para a validação de licença. Defina-a como variável de ambiente ou passe-a 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 no arranque e depois colocada em cache localmente durante 35 dias, para que o servidor possa funcionar totalmente offline após o primeiro arranque.

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

Opções disponíveis:

--host	Endereço de ligação (predefinição: 127.0.0.1)
--port	Porta de ligação (predefinição: 8000)
--api-key	Chave de API (alternativa à variável de ambiente)

Depois de iniciado, a API fica disponível na URL apresentada. A documentação Swagger interativa está em /docs.

5. Implementação com Docker (alternativa)

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

Contentor ú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 ficheiro .env com a sua chave de API:

.env

bash

PROMPTSHIELD_API_KEY=ps_live_your_key_here

A imagem Docker inclui:

Tesseract OCR com 7 pacotes de idioma (EN, FR, DE, ES, IT, NL, PT)

LibreOffice para a conversão de formatos do Office

Modelos de NLP do spaCy pré-instalados

Utilizador sem privilégios de root, verificações de estado, volume de dados persistente

6. Fluxo de trabalho da API

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

1Carregar. Envie o seu documento para o servidor

2Detetar. Execute o pipeline de deteção de dados pessoais (padrões + entidades + LLM opcional)

3Rever. Inspecione as regiões detetadas, edite ou confirme

4Anonimizar. Substitua os dados pessoais por códigos

5Transferir. 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 diretamente a partir da linha de comandos, sem iniciar um servidor:

Detetar dados pessoais e guardar 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 num ú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 num 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 a sua chave de API e processam os documentos localmente. Nenhum dado 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 da sua 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 estado 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)  ...

Transferir e instalar um pacote (sem necessidade 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

8. Expressões personalizadas

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.

Ficheiro 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

Fluxo de revisão: API → Ambiente de trabalho

📂

Deteção em lote

API ou CLI

📦

Pacote .psreview

documento + anotações

🖥️

Revisão no ambiente de trabalho

dispensar falsos positivos · adicionar dados pessoais em falta

✅

PDF anonimizados

Passo 1a — Detetar e exportar (CLI, num 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 — Detetar 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

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

POST

/api/documents/import-review

Importar pacote de revisão

Passo 2 — Importar para a aplicação de ambiente de trabalho

Passo 3 — Rever, editar e anonimizar

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

Para integrações avançadas, importe os módulos principais diretamente no seu código de Python. Isto dá-lhe controlo 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 ficheiros num 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 concebido para ambientes de confiança zero:

Todo o processamento acontece localmente. nenhum conteúdo de documento é alguma vez enviado para servidores externos

O registo de códigos permanece no seu dispositivo — o mesmo perímetro de confiança que os seus documentos de origem, nunca é carregado

A autenticação por chave de API impede o acesso não autorizado no modo auto-alojado

O Docker corre como utilizador sem privilégios de root, com privilégios mínimos

A chave de API é validada online uma vez e depois colocada em cache localmente para uso offline (TTL de 35 dias)

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. Em alternativa, para uma instalação a nível do sistema: python -m spacy download en_core_web_sm

O OCR não funciona em PDF digitalizados

Instale o Tesseract OCR e certifique-se de que está no seu PATH. No Windows, o instalador adiciona-o automaticamente.

Os ficheiros do Office não convertem

Instale o LibreOffice. O DOCX tem uma alternativa em Python puro, mas o XLSX/PPTX requerem o LibreOffice.

'Invalid API key' no arranque

Verifique que a sua chave começa por ps_live_ e que a sua subscrição está ativa. As chaves podem ser geridas em /developers/api-keys.

Documentos

POST

/api/documents/upload

Carregar documento

Carregue um documento para processamento. Suporta ficheiros PDF, DOCX, XLSX, PPTX e de imagem.

GET

/api/documents

Listar documentos

Obtenha todos os documentos carregados com o seu estado de deteção e anonimização.

GET

/api/documents/{id}

Obter documento

Obtenha informação detalhada sobre um documento específico, incluindo o número de páginas e o estado da deteção.

DELETE

/api/documents/{id}

Eliminar documento

Remova um documento e todos os dados associados do servidor.

Deteção

POST

/api/documents/{id}/detect

Detetar dados pessoais

POST

/api/documents/{id}/redetect

Voltar a detetar dados pessoais

Volte a executar a deteção com controlo total dos parâmetros. Aceita confidence_threshold, regex_types, ner_types, blacklist_terms e mais.

GET

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

Progresso da deteção

Obtenha o progresso de uma tarefa de deteção em curso (percentagem, página atual e estado).

GET

/api/documents/{id}/regions

Obter regiões

Obtenha todas as regiões de dados pessoais detetadas para 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

Defina 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

Substitua totalmente a lista de regiões de um documento. Use após editar as regiões do lado do cliente para enviar as alterações antes de anonimizar.

POST

/api/documents/{id}/anonymize

Anonimizar documento

Anonimize um documento substituindo os dados pessoais detetados por códigos. Devolve o documento processado.

GET

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

Transferir documento anonimizado

Transfira o resultado anonimizado. {type} é 'pdf' ou 'text'. O resultado é sempre apresentado em PDF (as entradas não-PDF são convertidas), pelo que 'pdf' é o formato principal.

POST

/api/documents/batch-anonymize

Anonimizar em lote

Anonimize vários documentos num único pedido. Até 50 documentos processados em simultâneo.

Descodificar

POST

/api/detokenize

Descodificar texto

Substitua os códigos numa cadeia de texto pelos seus valores originais do cofre.

POST

/api/detokenize/file

Descodificar ficheiro

Carregue um documento codificado e receba uma versão com todos os códigos restaurados nos valores originais.

Cofre e registo de códigos

GET

/api/vault/status

Estado do cofre

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

GET

/api/vault/tokens

Listar códigos

Obtenha todas as correspondências código-original armazenadas no cofre.

POST

/api/vault/export

Exportar cofre

Exporte todo o cofre como ficheiro JSON para cópia de segurança ou migração.

POST

/api/vault/import

Importar cofre

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

Estado

GET

/health

Verificação de estado

Devolve o estado de saúde do servidor. Use para monitorização e sondas de estado do balanceador de carga.

Definições

GET

/api/settings

Obter definições

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

PATCH

/api/settings

Atualizar definições

Atualize parcialmente as definições globais de deteção. As alterações aplicam-se a todas as deteções subsequentes.

GET

/api/settings/patterns

Listar padrões personalizados

Obtenha todos os padrões definidos pelo utilizador usados para a deteção personalizada de dados pessoais.

POST

/api/settings/patterns

Criar padrão personalizado

Adicione um novo padrão personalizado para a deteção de dados pessoais. Os padrões são avaliados em conjunto 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": "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

A classe PromptShield executa todo o pipeline localmente — detetar, anonimizar e descodificar em três chamadas. Todo o processamento acontece no seu dispositivo; nenhum dado sai dele.

Python SDK

bash

from promptshield import PromptShield

ps = PromptShield()

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

Pedido inválido. Parâmetros incorretos ou ficheiro corrompido / não suportado.

401

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

403

Proibido. A chave de API não tem o âmbito 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 ficheiro está protegido por palavra-passe.

500

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

503

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

Error Response Format

bash

{
  "detail": "Document not found: abc123"
}

Limites de taxa

A API auto-alojada não tem limites de taxa por predefinição. Pode configurar a limitação de taxa através de variáveis de ambiente, se necessário.