Referência da API

Início rápido

Integre o Entity Enricher em três passos:

Autenticação

Todos os endpoints da API (exceto início de sessão/registo) requerem autenticação. Utilize o cabeçalho X-API-Key com uma chave de acesso da organização:

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

Crie chaves de API a partir da página de chaves de API ou através de POST /api/auth/api-keys. Consulte o guia de chaves de API para detalhes sobre os tipos de chave e as permissões.

Principais endpoints

Streaming SSE

As operações de enriquecimento, geração de schema e fusion utilizam Server-Sent Events para acompanhar o progresso em tempo real. Inicie um trabalho, obtenha um job_id e depois ligue-se ao stream SSE:

Exemplo em Python

Um fluxo de trabalho completo que lista esquemas, inicia o enriquecimento, transmite resultados e obtém o registo 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))

Exemplo com curl

Inicie um enriquecimento em lote com dois modelos e transmita os 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'

Tratamento de erros

As respostas de erro incluem um campo detail com uma mensagem de erro legível. As falhas de plano e de faturação (402) trazem ainda um corpo estruturado com um code estável — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — além dos números de limite e de utilização relevantes, para que um cliente possa decidir com base na causa em vez de interpretar texto corrido. Os fluxos SSE emitem um tipo de evento error antes do evento terminal completed se algo falhar a meio do fluxo.

Chaves Compostas do Model

Os modelos são identificados por chaves compostas no formato provider_name::model_name. Use GET /api/enrichment/options para listar os modelos disponíveis e as respetivas chaves.

O parâmetro model é opcional no enriquecimento, na geração de esquemas e na geração de amostras: omita-o (ou passe o literal "auto") e o servidor escolhe o modelo predefinido da sua organização — a predefinição por tarefa fixada, se estiver definida nas Definições, caso contrário o modelo com a melhor pontuação global dos seus benchmarks de origem de pontuação. O campo default_models da resposta de opções mostra para que o auto resolve atualmente, e um evento SSE model_auto_selected comunica a escolha em cada tarefa. O auto resolve sempre para um único modelo (nunca aciona fusão); para pipelines reproduzíveis, continue a passar modelos explícitos.

As opções do pedido restringem a seleção automática: com enable_web_search: true apenas os modelos com capacidade de pesquisa na web são considerados (o campo default_models_web_search da resposta de opções pré-visualiza essa seleção) e os anexos binários exigem um modelo que os consiga ler (PDF, visão, áudio). Quando nenhum modelo elegível satisfaz as restrições, o pedido falha com HTTP 400 no_capable_default_model em vez de descartar silenciosamente a opção.

Documentação interativa da API

A aplicação inclui documentação de API interativa com exemplos de pedido/resposta. Requer autenticação de administrador para aceder: