Documentazione API

Integra l'anonimizzazione di testo rispettosa della privacy di ANOXY nelle tue applicazioni con la nostra semplice API REST.

Avvio rapido

Ottieni la tua chiave API

Registrati nella dashboard e crea una chiave API.

Effettua la tua prima richiesta

Usa l'endpoint /v1/anonymize per iniziare a proteggere i dati sensibili.

Ripristina il testo originale

Usa lo stesso ID sessione con /v1/deanonymize per recuperare il testo originale.

Autenticazione

Tutte le richieste API richiedono autenticazione. ANOXY supporta due metodi di autenticazione:

Chiave API

Includi la tua chiave API nell'header X-API-Key. Crea le chiavi nella tua dashboard.

X-API-Key: YOUR_API_KEY

Token JWT Bearer

Per integrazioni SSO e OAuth, passa un token JWT nell'header Authorization. I token sono emessi dal provider di identità di ANOXY.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

POST/v1/anonymize

Anonimizza il testo rilevando e sostituendo le informazioni personali (PII) con token coerenti.

Corpo della richiesta

textstringobbligatorio

Il testo da anonimizzare.

languagestringopzionale

Codice lingua (es. "en", "pl"). Predefinito: "en".

session_idstringopzionale

ID sessione personalizzato. Se non fornito, ne verrà generato uno.

Richiesta di esempio

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"
  }'

Risposta di esempio

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

Ripristina il testo originale usando la mappatura della sessione. Richiede un ID sessione valido da una precedente anonimizzazione.

Corpo della richiesta

textstringobbligatorio

Il testo anonimizzato da ripristinare.

session_idstringobbligatorio

L'ID sessione dalla richiesta di anonimizzazione.

Richiesta di esempio

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"
  }'

Risposta di esempio

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

Rileva entità PII nel testo senza anonimizzare. Restituisce posizioni, tipi e punteggi di confidenza delle entità preservando il testo originale.

Corpo della richiesta

textstringobbligatorio

Il testo da analizzare per le entità PII.

languagestringopzionale

Codice lingua (es. "en", "pl"). Predefinito: "en".

entity_typesstring[] | stringopzionale

Filtra tipi di entità specifici. Accetta un array JSON o una stringa separata da virgole (es. "PERSON,EMAIL_ADDRESS").

Richiesta di esempio

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"
  }'

Risposta di esempio

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

Carica un file documento per l'anonimizzazione. Supporta PDF, DOCX, XLSX, CSV, PPTX, immagini (OCR) e oltre 10 altri formati. Restituisce un ID lavoro per scaricare il risultato.

Corpo della richiesta

Content-Type: multipart/form-data

filebinaryobbligatorio

Il file documento da anonimizzare (max 50 MB).

modestringopzionale

Modalità di anonimizzazione: "anonymize" (predefinita, irreversibile) o "pseudonymize" (reversibile con sessione).

languagestringopzionale

Codice lingua (es. "en", "pl"). Predefinito: "en".

Richiesta di esempio

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"

Formati supportati

PDFDOCXXLSXCSVPPTXRTFHTMLTXTXMLJSONEMLMDPNGJPGTIFFBMP

Risposta di esempio

{
  "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 risposta

Tutte le risposte API seguono una struttura envelope JSON coerente. Le risposte di successo avvolgono i dati nel campo "data", le risposte di errore forniscono un oggetto errore strutturato.

Successo

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

Errore

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

Catalogo endpoint

Elenco completo degli endpoint API disponibili.

Metodo	Endpoint	Descrizione	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

Codici di errore

400 Bad Request

Parametri di richiesta non validi o JSON malformato.

401 Unauthorized

Chiave API mancante o non valida.

402 Payment Required

Quota superata. Aggiorna il tuo piano o attendi il ripristino della quota.

404 Not Found

Sessione non trovata o scaduta (per deanonimizzazione).

429 Too Many Requests

Limite di frequenza superato. Controlla l'header X-RateLimit-Reset per sapere quando riprovare.

500 Internal Server Error

Errore del server. Riprova o contatta il supporto.

Limiti di frequenza

I limiti di frequenza variano in base al piano:

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

Header limiti di frequenza

Ogni risposta autenticata include header con i limiti di frequenza:

X-RateLimit-Limit

Numero massimo di richieste consentite al minuto per il tuo piano.

X-RateLimit-Remaining

Numero di richieste rimanenti nella finestra corrente.

X-RateLimit-Reset

Timestamp Unix (secondi) di quando si ripristina la finestra dei limiti.

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

Hai bisogno di aiuto?

Il nostro team è qui per supportare la tua integrazione.

Contatta il supporto Vai alla dashboard