Справочник API

Быстрый старт

Интегрируйте Entity Enricher за три шага:

Аутентификация

Все конечные точки API (кроме входа/регистрации) требуют аутентификации. Используйте заголовок X-API-Key с ключом доступа организации:

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

Создавайте API-ключи на странице «API-ключи» или через POST /api/auth/api-keys. Подробнее о типах ключей и разрешениях см. в руководстве по API-ключам.

Ключевые эндпоинты

Потоковая передача SSE

Операции обогащения, генерации схем и слияния используют Server-Sent Events для отображения прогресса в реальном времени. Запустите задачу, получите job_id, затем подключитесь к потоку SSE:

Пример на Python

Полный рабочий процесс, который выводит список схем, запускает обогащение, передаёт результаты потоком и извлекает итоговую запись:

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

Запустите пакетное обогащение с двумя моделями и получайте результаты в потоке:

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

Обработка ошибок

Ответы с ошибками содержат поле detail с понятным человеку сообщением об ошибке. Ошибки плана и биллинга (402) дополнительно возвращают структурированное тело со стабильным кодом code — prompt_limit_reached, insufficient_credits, model_limit_exceeded, benchmarks_not_in_plan — а также соответствующие значения лимита и использования, чтобы клиент мог ветвить логику по причине, а не разбирать текст. В потоках SSE, если сбой происходит в середине потока, отправляется событие типа error перед завершающим событием completed.

Составные ключи модели

Модели идентифицируются составными ключами в формате provider_name::model_name. Используйте GET /api/enrichment/options, чтобы получить список доступных моделей и их ключей.

Параметр model необязателен при обогащении, генерации схемы и генерации образцов: опустите его (или передайте буквально "auto"), и сервер выберет модель по умолчанию вашей организации — закреплённое значение по умолчанию для задачи, если оно задано в настройках, иначе модель с лучшей общей оценкой из ваших бенчмарков-источников оценок. Поле default_models в ответе options показывает, во что сейчас разрешается auto, а событие SSE model_auto_selected сообщает о выборе для каждого задания. Авто всегда разрешается в одну модель (оно никогда не запускает слияние); для воспроизводимых конвейеров продолжайте передавать явные модели.

Параметры запроса ограничивают автоматический выбор: при enable_web_search: true рассматриваются только модели с поддержкой веб-поиска (поле default_models_web_search в ответе с параметрами показывает предварительный выбор), а бинарные вложения требуют модели, способной их читать (PDF, изображения, аудио). Если ни одна подходящая модель не удовлетворяет ограничениям, запрос завершается с ошибкой HTTP 400 no_capable_default_model вместо того, чтобы молча отбросить параметр.

Интерактивная документация API

Приложение включает интерактивную документацию API с примерами запросов и ответов. Для доступа требуется аутентификация администратора: