Riferimento API

Avvio rapido

Integra Entity Enricher in tre passaggi:

Autenticazione

Tutti gli endpoint API (tranne login/registrazione) richiedono l'autenticazione. Utilizzare l'header X-API-Key con una chiave di accesso dell'organizzazione:

curl -H "X-API-Key: ent_your_key_here" \
     https://your-instance.example.com/api/enrichment/options

Crea chiavi API dalla pagina Chiavi API o tramite POST /api/auth/api-keys. Consulta la guida alle chiavi API per i dettagli sui tipi di chiave e i permessi.

Endpoint principali

Streaming SSE

Le operazioni di arricchimento, generazione degli schemi e fusione utilizzano i Server-Sent Events per il progresso in tempo reale. Avviare un job, ottenere un job_id, quindi connettersi allo stream SSE:

Esempio Python

Un flusso di lavoro completo che elenca gli schemi, avvia l'arricchimento, trasmette i risultati in streaming e recupera il record finale:

import httpx
import json

BASE = "https://your-instance.example.com"
KEY = "ent_your_api_key"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1. List saved schemas
schemas = httpx.get(f"{BASE}/api/schema/saved", headers=HEADERS).json()
schema_id = schemas["schemas"][0]["id"]

# 2. Start enrichment
resp = httpx.post(f"{BASE}/api/single/enrich/stream", headers=HEADERS, json={
    "entity_data": {"name": "Moderna Inc", "country": "US"},
    "schema_id": schema_id,
    "models": ["anthropic::claude-sonnet-4-5-20250514"],
    "strategy": "multi_expertise",
})
job_id = resp.json()["job_id"]

# 3. Stream SSE events
record_id = None
with httpx.stream("GET", f"{BASE}/api/llm/stream/{job_id}", headers=HEADERS) as stream:
    for line in stream.iter_lines():
        if not line.startswith("data: "):
            continue
        event = json.loads(line[6:])

        if event["type"] == "model_completed" and event.get("record_id"):
            record_id = event["record_id"]
        elif event["type"] == "completed":
            break

# 4. Retrieve the enrichment record
if record_id:
    record = httpx.get(f"{BASE}/api/records/{record_id}", headers=HEADERS).json()
    print(json.dumps(record["structured_output"], indent=2))

Esempio curl

Avvia un arricchimento batch con due model ed esegui lo streaming dei risultati:

# Start batch enrichment
JOB_ID=$(curl -s -X POST \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/api/enrichment/batch/start" \
  -d '{
    "entities": [
      {"name": "Pfizer Inc", "country": "US"},
      {"name": "Roche", "country": "CH"}
    ],
    "schema_id": "your-schema-uuid",
    "models": ["anthropic::claude-sonnet-4-5-20250514", "openai::gpt-4o"],
    "strategy": "multi_expertise",
    "arbitration_model": "anthropic::claude-sonnet-4-5-20250514"
  }' | jq -r '.job_id')

# Stream events
curl -N -H "X-API-Key: $KEY" "$BASE/api/llm/stream/$JOB_ID"

# List resulting records
curl -s -H "X-API-Key: $KEY" \
  "$BASE/api/records?type=enrichment&page_size=10" | jq '.records'

Gestione degli errori

Le risposte di errore includono un campo detail con un messaggio di errore leggibile. Gli errori relativi al piano e alla fatturazione (402) contengono inoltre un corpo strutturato con un code stabile — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — oltre ai valori di limite e di utilizzo pertinenti, così che un client possa distinguere la causa anziché analizzare il testo. I flussi SSE emettono un evento di tipo error prima dell'evento finale completed se qualcosa non riesce durante lo streaming.

Chiavi composite del modello

I modelli sono identificati da chiavi composite nel formato provider_name::model_name. Utilizzare GET /api/enrichment/options per elencare i modelli disponibili e le relative chiavi.

Il parametro model è facoltativo per l'arricchimento, la generazione di schema e la generazione di campioni: ometterlo (oppure passare il valore letterale "auto") e il server sceglie il modello predefinito della Sua organizzazione — il predefinito per attività fissato se ne è impostato uno nelle Impostazioni, altrimenti il modello con il miglior punteggio complessivo dai Suoi benchmark di origine del punteggio. Il campo default_models della risposta options mostra a quale modello si risolve attualmente auto, mentre un evento SSE model_auto_selected segnala la scelta per ogni job. Auto si risolve sempre in un singolo modello (non attiva mai la fusion); per pipeline riproducibili, continui a passare modelli espliciti.

Le opzioni della richiesta vincolano la selezione automatica: con enable_web_search: true vengono considerati solo i modelli in grado di effettuare ricerche web (il campo default_models_web_search della risposta con le opzioni mostra un'anteprima di tale selezione) e gli attachment binari richiedono un modello in grado di leggerli (PDF, visione, audio). Quando nessun modello idoneo soddisfa i vincoli, la richiesta ha esito negativo con HTTP 400 no_capable_default_model anziché ignorare silenziosamente l'opzione.

Documentazione API interattiva

L'applicazione include una documentazione API interattiva con esempi di richiesta/risposta. Per accedervi è richiesta l'autenticazione come amministratore: