Referencia de la API

Inicio rápido

Integre Entity Enricher en tres pasos:

Autenticación

Todos los endpoints de la API (excepto login/register) requieren autenticación. Use la cabecera X-API-Key con una clave de acceso de la organización:

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

Cree claves de API desde la página Claves de API o mediante POST /api/auth/api-keys. Consulte la guía de claves de API para más detalles sobre los tipos de claves y los permisos.

Endpoints clave

Streaming SSE

Las operaciones de enriquecimiento, generación de esquemas y fusión utilizan Server-Sent Events para el progreso en tiempo real. Inicie un trabajo, obtenga un job_id y, a continuación, conéctese al flujo SSE:

Ejemplo en Python

Un flujo de trabajo completo que enumera esquemas, inicia el enriquecimiento, transmite resultados y recupera el registro 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))

Ejemplo con curl

Inicie un enriquecimiento por lotes con dos modelos y transmita los resultados:

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

Gestión de errores

Las respuestas de error incluyen un campo detail con un mensaje de error legible. Los fallos de plan y facturación (402) llevan además un cuerpo estructurado con un code estable — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — junto con las cifras de límite y uso pertinentes, de modo que un cliente puede bifurcar según la causa en lugar de analizar texto. Los flujos SSE emiten un evento de tipo error antes del evento final completed si algo falla a mitad del flujo.

Claves compuestas del modelo

Los modelos se identifican mediante claves compuestas con el formato provider_name::model_name. Utilice GET /api/enrichment/options para listar los modelos disponibles y sus claves.

El parámetro model es opcional en el enriquecimiento, la generación de esquemas y la generación de muestras: omítalo (o pase el literal "auto") y el servidor elige el modelo predeterminado de su organización: el predeterminado por tarea fijado si hay uno configurado en Ajustes, de lo contrario el modelo con la mejor puntuación global de sus benchmarks de origen de puntuación. El campo default_models de la respuesta de opciones muestra a qué se resuelve auto actualmente, y un evento SSE model_auto_selected informa de la elección en cada trabajo. Auto siempre se resuelve en un único modelo (nunca activa la fusión); para canalizaciones reproducibles, siga pasando modelos explícitos.

Las opciones de la solicitud restringen la selección automática: con enable_web_search: true solo se tienen en cuenta los modelos con capacidad de búsqueda web (el campo default_models_web_search de la respuesta de opciones muestra una vista previa de esa selección), y los adjuntos binarios requieren un modelo que pueda leerlos (PDF, visión, audio). Cuando ningún modelo elegible cumple las restricciones, la solicitud falla con HTTP 400 no_capable_default_model en lugar de descartar la opción de forma silenciosa.

Documentación interactiva de la API

La aplicación incluye documentación interactiva de la API con ejemplos de solicitud/respuesta. Requiere autenticación de administrador para acceder: