API-Referenz

Schnellstart

Integrieren Sie Entity Enricher in drei Schritten:

Authentifizierung

Alle API-Endpunkte (außer Login/Registrierung) erfordern eine Authentifizierung. Verwenden Sie den X-API-Key-Header mit einem Zugriffsschlüssel der Organisation:

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

Erstellen Sie API-Schlüssel über die Seite „API-Schlüssel“ oder via POST /api/auth/api-keys. Siehe den API-Schlüssel-Leitfaden für Details zu Schlüsseltypen und Berechtigungen.

Wichtige Endpunkte

SSE-Streaming

Anreicherung, Schema-Generierung und Fusion-Operationen nutzen Server-Sent Events für Echtzeit-Fortschritt. Starten Sie einen Job, erhalten Sie eine job_id und verbinden Sie sich dann mit dem SSE-Stream:

Python-Beispiel

Ein vollständiger Workflow, der Schemas auflistet, eine Anreicherung startet, Ergebnisse streamt und den endgültigen Datensatz abruft:

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

Starten Sie eine Batch-Anreicherung mit zwei Modellen und streamen Sie die Ergebnisse:

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

Fehlerbehandlung

Fehlerantworten enthalten ein Feld detail mit einer lesbaren Fehlermeldung. Tarif- und Abrechnungsfehler (402) liefern zusätzlich einen strukturierten Body mit einem stabilen code — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — sowie die betreffenden Grenz- und Nutzungswerte, sodass ein Client anhand der Ursache verzweigen kann, statt Fließtext zu parsen. SSE-Streams senden einen Ereignistyp error vor dem abschließenden Ereignis completed, falls mitten im Stream etwas fehlschlägt.

Zusammengesetzte Modellschlüssel

Modelle werden durch zusammengesetzte Schlüssel im Format provider_name::model_name identifiziert. Verwenden Sie GET /api/enrichment/options, um verfügbare Modelle und ihre Schlüssel aufzulisten.

Der Modellparameter ist bei Anreicherung, Schemagenerierung und Beispielgenerierung optional: Lassen Sie ihn weg (oder übergeben Sie das Literal "auto"), und der Server wählt das Standardmodell Ihrer Organisation — die angeheftete aufgabenspezifische Vorgabe, falls in den Einstellungen festgelegt, andernfalls das Modell mit der besten Gesamtbewertung aus Ihren Benchmarks als Bewertungsquelle. Das Feld default_models der Optionsantwort zeigt, worauf Auto derzeit aufgelöst wird, und ein model_auto_selected-SSE-Ereignis meldet die Auswahl bei jedem Auftrag. Auto wird immer zu einem einzigen Modell aufgelöst (es löst niemals Fusion aus); für reproduzierbare Pipelines übergeben Sie weiterhin explizite Modelle.

Anfrageoptionen schränken die automatische Auswahl ein: Mit enable_web_search: true werden nur websuchfähige Modelle berücksichtigt (das Feld default_models_web_search der Optionsantwort zeigt diese Auswahl in der Vorschau), und binäre Anhänge erfordern ein Modell, das sie lesen kann (PDF, Vision, Audio). Wenn kein geeignetes Modell die Einschränkungen erfüllt, schlägt die Anfrage mit HTTP 400 no_capable_default_model fehl, anstatt die Option stillschweigend zu verwerfen.

Interaktive API-Dokumentation

Die Anwendung enthält eine interaktive API-Dokumentation mit Beispielen für Anfragen/Antworten. Für den Zugriff ist eine Admin-Authentifizierung erforderlich: