Référence API

Démarrage rapide

Intégrez Entity Enricher en trois étapes :

Authentification

Tous les points de terminaison de l'API (sauf connexion/inscription) nécessitent une authentification. Utilisez l'en-tête X-API-Key avec une clé d'accès d'organisation :

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

Créez des clés API depuis la page Clés API ou via POST /api/auth/api-keys. Consultez le guide des clés API pour plus de détails sur les types de clés et les permissions.

Principaux points de terminaison

Streaming SSE

Les opérations d'enrichissement, de génération de schéma et de fusion utilisent les Server-Sent Events pour une progression en temps réel. Lancez une tâche, obtenez un job_id, puis connectez-vous au flux SSE :

Exemple Python

Un flux de travail complet qui liste les schémas, démarre l'enrichissement, diffuse les résultats et récupère l'enregistrement final :

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))

Exemple curl

Lancez un enrichissement par traitement par lot avec deux modèles et diffusez les résultats en continu :

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

Gestion des erreurs

Les réponses d'erreur comportent un champ detail contenant un message d'erreur lisible. Les échecs liés à l'offre et à la facturation (402) transportent en plus un corps structuré avec un code stable — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — ainsi que les valeurs de limite et d'utilisation concernées, afin qu'un client puisse traiter la cause sans analyser du texte. Les flux SSE émettent un événement de type error avant l'événement final completed si une erreur survient en cours de flux.

Clés composites de modèle

Les modèles sont identifiés par des clés composites au format provider_name::model_name. Utilisez GET /api/enrichment/options pour lister les modèles disponibles et leurs clés.

Le paramètre model est optionnel pour l'enrichissement, la génération de schéma et la génération d'échantillons : omettez-le (ou transmettez la valeur littérale "auto") et le serveur choisit le modèle par défaut de votre organisation — le défaut par tâche épinglé si un est défini dans les Paramètres, sinon le modèle avec le meilleur score global issu de vos benchmarks source de scoring. Le champ default_models de la réponse des options indique vers quoi auto résout actuellement, et un événement SSE model_auto_selected signale le choix pour chaque tâche. Auto résout toujours vers un seul modèle (il ne déclenche jamais la fusion) ; pour des pipelines reproductibles, continuez à transmettre des modèles explicites.

Les options de la requête contraignent la sélection automatique : avec enable_web_search: true, seuls les modèles compatibles avec la recherche web sont pris en compte (le champ default_models_web_search de la réponse d'options prévisualise cette sélection), et les pièces jointes binaires nécessitent un modèle capable de les lire (PDF, vision, audio). Lorsqu'aucun modèle éligible ne satisfait les contraintes, la requête échoue avec une erreur HTTP 400 no_capable_default_model au lieu d'ignorer silencieusement l'option.

Documentation API interactive

L'application inclut une documentation API interactive avec des exemples de requêtes/réponses. Nécessite une authentification administrateur pour y accéder :