Documentação da API

Integre a anonimização de texto com preservação de privacidade do ANOXY nas suas aplicações com a nossa API REST simples.

Início rápido

Obtenha a sua chave API

Registe-se no painel e crie uma chave API.

Faça o seu primeiro pedido

Utilize o endpoint /v1/anonymize para começar a proteger dados sensíveis.

Restaure o texto original

Utilize o mesmo ID de sessão com /v1/deanonymize para recuperar o texto original.

Autenticação

Todos os pedidos API requerem autenticação. O ANOXY suporta dois métodos de autenticação:

Chave API

Inclua a sua chave API no cabeçalho X-API-Key. Crie chaves no seu painel.

X-API-Key: YOUR_API_KEY

Token JWT Bearer

Para integrações SSO e OAuth, passe um token JWT no cabeçalho Authorization. Os tokens são emitidos pelo provedor de identidade do ANOXY.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

POST/v1/anonymize

Anonimize texto detetando e substituindo dados pessoais (PII) por tokens consistentes.

Corpo do pedido

textstringobrigatório

O texto a anonimizar.

languagestringopcional

Código de idioma (p. ex., "en", "pt"). Predefinido: "en".

session_idstringopcional

ID de sessão personalizado. Se não for fornecido, será gerado um.

Exemplo de pedido

curl -X POST https://app.anoxy.ai/v1/anonymize \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "John Smith lives at 123 Main St, New York. His email is john@example.com.",
    "language": "en",
    "session_id": "optional-session-id"
  }'

Exemplo de resposta

{
  "session_id": "abc-123-def-456",
  "anonymized_text": "<PERSON_1> lives at <LOCATION_1>. His email is <EMAIL_1>.",
  "entities_found": [
    {
      "entity_type": "PERSON",
      "start": 0,
      "end": 10,
      "text": "John Smith",
      "anonymized_token": "<PERSON_1>"
    },
    {
      "entity_type": "LOCATION",
      "start": 20,
      "end": 42,
      "text": "123 Main St, New York",
      "anonymized_token": "<LOCATION_1>"
    },
    {
      "entity_type": "EMAIL_ADDRESS",
      "start": 57,
      "end": 76,
      "text": "john@example.com",
      "anonymized_token": "<EMAIL_1>"
    }
  ],
  "quota_used": 1250,
  "quota_remaining": 8750,
  "processing_time_ms": 45.2
}

POST/v1/deanonymize

Restaure o texto original utilizando o mapeamento da sessão. Requer um ID de sessão válido de uma anonimização anterior.

Corpo do pedido

textstringobrigatório

O texto anonimizado a restaurar.

session_idstringobrigatório

O ID de sessão do pedido de anonimização.

Exemplo de pedido

curl -X POST https://app.anoxy.ai/v1/deanonymize \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "<PERSON_1> lives at <LOCATION_1>. His email is <EMAIL_1>.",
    "session_id": "your-session-id"
  }'

Exemplo de resposta

{
  "original_text": "John Smith lives at 123 Main St, New York. His email is john@example.com.",
  "session_id": "abc-123-def-456",
  "processing_time_ms": 12.4
}

POST/v1/text/detect

Detetar entidades PII no texto sem anonimizar. Retorna localizações, tipos e pontuações de confiança das entidades, preservando o texto original.

Corpo do pedido

textstringobrigatório

O texto a analisar para entidades PII.

languagestringopcional

Código de idioma (p. ex., "en", "pt"). Predefinido: "en".

entity_typesstring[] | stringopcional

Filtrar tipos de entidades específicos. Aceita um array JSON ou uma string separada por vírgulas (ex. "PERSON,EMAIL_ADDRESS").

Exemplo de pedido

curl -X POST https://app.anoxy.ai/v1/text/detect \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "John Smith lives at 123 Main St. Email: john@example.com",
    "language": "en"
  }'

Exemplo de resposta

{
  "status": "success",
  "data": {
    "text": "John Smith lives at 123 Main St. Email: john@example.com",
    "entities_found": [
      {"entity_type": "PERSON", "start": 0, "end": 10, "text": "John Smith", "score": 0.95},
      {"entity_type": "LOCATION", "start": 20, "end": 31, "text": "123 Main St", "score": 0.88},
      {"entity_type": "EMAIL_ADDRESS", "start": 40, "end": 56, "text": "john@example.com", "score": 0.99}
    ],
    "entity_summary": {"PERSON": 1, "LOCATION": 1, "EMAIL_ADDRESS": 1}
  }
}

POST/v1/documents/anonymize

Carregar um ficheiro de documento para anonimização. Suporta PDF, DOCX, XLSX, CSV, PPTX, imagens (OCR) e mais de 10 outros formatos. Retorna um ID de tarefa para descarregar o resultado.

Corpo do pedido

Content-Type: multipart/form-data

filebinaryobrigatório

O ficheiro de documento a anonimizar (máx. 50 MB).

modestringopcional

Modo de anonimização: "anonymize" (padrão, irreversível) ou "pseudonymize" (reversível com sessão).

languagestringopcional

Código de idioma (p. ex., "en", "pt"). Predefinido: "en".

Exemplo de pedido

curl -X POST https://app.anoxy.ai/v1/documents/anonymize \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "mode=anonymize" \
  -F "language=en"

Formatos suportados

PDFDOCXXLSXCSVPPTXRTFHTMLTXTXMLJSONEMLMDPNGJPGTIFFBMP

Exemplo de resposta

{
  "status": "success",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "contract_anonymized.pdf",
    "entities_count": 23,
    "processing_time_ms": 1250.5,
    "download_url": "/v1/history/550e8400.../download"
  }
}

Formato de resposta

Todas as respostas da API seguem uma estrutura de envelope JSON consistente. Respostas de sucesso envolvem os dados num campo "data", respostas de erro fornecem um objeto de erro estruturado.

Sucesso

{
  "status": "success",
  "data": { ... },
  "meta": {
    "version": "4.10.10",
    "processing_time_ms": 45.2
  }
}

Erro

{
  "status": "error",
  "error": {
    "type": "validation_error",
    "message": "Text is required."
  }
}

Catálogo de endpoints

Lista completa de endpoints API disponíveis.

Método	Endpoint	Descrição	Auth
POST	/v1/anonymize	Anonymize text, replacing PII with tokens	Required
POST	/v1/deanonymize	Restore original text using session mapping	Required
POST	/v1/text/detect	Detect PII entities without anonymizing	Required
POST	/v1/documents/anonymize	Upload and anonymize a document file	Required
POST	/v1/text/anonymize-batch	Anonymize up to 20 text items in one request	Required
GET	/v1/countries	List supported countries and entity types	None
GET	/v1/history	List anonymization history (paginated, sortable)	Required
GET	/v1/history/{job_id}	Get job detail with entity breakdown	Required
GET	/v1/history/{job_id}/download	Download anonymized result file	Required
POST	/v1/history/batch-delete	Batch delete jobs	Required
GET	/v1/quota	Check current quota usage and limits	Required
GET	/v1/api-keys	List your API keys	Required
POST	/v1/api-keys	Create a new API key	Required
DELETE	/v1/api-keys/{id}	Revoke an API key	Required
GET	/v1/billing/subscription	Get current subscription details	Required
GET	/health	Health check endpoint	None

Códigos de erro

400 Bad Request

Parâmetros de pedido inválidos ou JSON malformado.

401 Unauthorized

Chave API em falta ou inválida.

402 Payment Required

Quota excedida. Faça upgrade do seu plano ou aguarde o reinicio da quota.

404 Not Found

Sessão não encontrada ou expirada (para desanonimização).

429 Too Many Requests

Limite de taxa excedido. Consulte o cabeçalho X-RateLimit-Reset para saber quando pode tentar novamente.

500 Internal Server Error

Erro de servidor. Tente novamente ou contacte o suporte.

Limites de taxa

Os limites de taxa variam conforme o plano:

Free: 10 requests/minute, 1,000 tokens/month
Pro: 100 requests/minute, 100,000 tokens/month
Team: 1,000 requests/minute, 1,000,000 tokens/month
Enterprise: 1,000 requests/minute, unlimited tokens

Cabeçalhos de limite de taxa

Cada resposta autenticada inclui cabeçalhos de limite de taxa:

X-RateLimit-Limit

Número máximo de pedidos permitidos por minuto para o seu plano.

X-RateLimit-Remaining

Número de pedidos restantes na janela atual.

X-RateLimit-Reset

Timestamp Unix (segundos) quando a janela de limite reinicia.

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707523260

Precisa de ajuda?

A nossa equipa está aqui para apoiar a sua integração.

Contactar suporte Ver painel