API Reference

Quick Start

Integrate Entity Enricher in three steps:

Authentication

All API endpoints (except login/register) require authentication. Use the X-API-Key header with an organization access key:

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

Create API keys from the API Keys page or via POST /api/auth/api-keys. See the API Keys guide for details on key types and permissions.

Key Endpoints

SSE Streaming

Enrichment, schema generation, and fusion operations use Server-Sent Events for real-time progress. Start a job, get a job_id, then connect to the SSE stream:

Python Example

A complete workflow that lists schemas, starts enrichment, streams results, and retrieves the final record:

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 Example

Start a batch enrichment with two models and stream the results:

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

Error Handling

Error responses include a detail field with a human-readable error message. Plan and billing failures (402) additionally carry a structured body with a stable code — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — plus the relevant limit and usage numbers, so a client can branch on the cause instead of parsing prose. SSE streams emit an error event type before the terminal completed event if something fails mid-stream.

Model Composite Keys

Models are identified by composite keys in the format provider_name::model_name. Use GET /api/enrichment/options to list available models and their keys.

The model parameter is optional on enrichment, schema generation, and sample generation: omit it (or pass the literal "auto") and the server picks your organization's default model — the pinned per-task default if one is set in Settings, otherwise the model with the best overall score from your scoring-source benchmarks. The options response's default_models field shows what auto currently resolves to, and a model_auto_selected SSE event reports the pick on every job. Auto always resolves to a single model (it never triggers fusion); for reproducible pipelines, keep passing explicit models.

Request options constrain the auto pick: with enable_web_search: true only web-search-capable models are considered (the options response's default_models_web_search field previews that pick), and binary attachments require a model that can read them (PDF, vision, audio). When no eligible model satisfies the constraints the request fails with HTTP 400 no_capable_default_model instead of silently dropping the option.

Interactive API Documentation

The application includes interactive API documentation with request/response examples. Requires admin authentication to access: