API-referentie

Snel aan de slag

Integreer Entity Enricher in drie stappen:

Authenticatie

Alle API-eindpunten (behalve inloggen/registreren) vereisen authenticatie. Gebruik de X-API-Key-header met een toegangssleutel van de organisatie:

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

Maak API-sleutels aan op de pagina API-sleutels of via POST /api/auth/api-keys. Zie de gids voor API-sleutels voor details over sleuteltypes en permissies.

Belangrijkste endpoints

SSE-streaming

Verrijking, schemageneratie en fusiebewerkingen gebruiken Server-Sent Events voor realtime voortgang. Start een taak, ontvang een job_id en maak vervolgens verbinding met de SSE-stream:

Python-voorbeeld

Een complete workflow die schema's opsomt, verrijking start, resultaten streamt en het uiteindelijke record ophaalt:

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

curl-voorbeeld

Start een batch-enrichment met twee modellen en stream de resultaten:

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

Foutafhandeling

Foutantwoorden bevatten een veld detail met een leesbare foutmelding. Fouten rond abonnement en facturatie (402) bevatten daarnaast een gestructureerde body met een stabiele code — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — plus de betreffende limiet- en gebruikscijfers, zodat een client op de oorzaak kan vertakken in plaats van tekst te parsen. SSE-streams sturen een error-event vóór het afsluitende completed-event als er halverwege de stream iets misgaat.

Samengestelde sleutels van model

Modellen worden geïdentificeerd door samengestelde sleutels in de indeling provider_name::model_name. Gebruik GET /api/enrichment/options om beschikbare modellen en hun sleutels op te sommen.

De modelparameter is optioneel bij verrijking, schemageneratie en samplegeneratie: laat hem weg (of geef letterlijk "auto" mee) en de server kiest het standaardmodel van je organisatie — de vastgezette standaard per taak als die is ingesteld in Instellingen, anders het model met de beste algehele score uit je scorebron-benchmarks. Het veld default_models in de options-response toont waar auto momenteel naar verwijst, en een model_auto_selected-SSE-event rapporteert de keuze bij elke taak. Auto verwijst altijd naar één enkel model (het activeert nooit fusie); voor reproduceerbare pipelines blijf je expliciete modellen meegeven.

Verzoekopties beperken de automatische keuze: met enable_web_search: true worden alleen modellen die kunnen zoeken op internet overwogen (het veld default_models_web_search in de optie-respons geeft een voorbeeld van die keuze), en binaire bijlagen vereisen een model dat ze kan lezen (PDF, beeld, audio). Wanneer geen enkel geschikt model aan de beperkingen voldoet, mislukt het verzoek met HTTP 400 no_capable_default_model in plaats van de optie stilzwijgend te negeren.

Interactieve API-documentatie

De applicatie bevat interactieve API-documentatie met voorbeelden van aanvragen en antwoorden. Vereist admin-authenticatie voor toegang: