API agent и ingestion endpoints

Здесь перечислены все эндпоинты, которые вызывает Flaree Agent, и OTLP-маршруты шлюза Ingestion. Весь трафик идёт egress-only от агента к бэкенду по HTTPS и авторизуется заголовком X-Flaree-Token: <agent-token>.

Agent API

Wire-протокол агента на https://api.flaree.ru:

Метод	Путь	Когда вызывается	Успешный ответ
POST	/api/agent/register	при старте процесса	200 — AgentId, minimumVersion, latestVersion
GET	/api/agent/config	каждые 30 секунд	200 — список jobs и ConfigHash
POST	/api/agent/checkins	батч результатов проверок	200
POST	/api/agent/heartbeat	раз в минуту: версия, uptime, CPU/RAM	204 No Content
POST	/api/agent/inventory	при регистрации и каждые 6 часов	204 No Content

Ingestion endpoints

Логи и метрики (в том числе принятые OTLP receiver'ом агента) уходят в шлюз ingestion. Аутентификация та же — X-Flaree-Token:

Метод	Путь	Тело	Успешный ответ
POST	/api/agent/logs	JSON-батч записей логов	202 Accepted
POST	/api/agent/metrics	JSON-батч точек метрик	202 Accepted

warning

Маршрутов /ingest/logs, /ingest/metrics, /ingest/heartbeat не существует. Логи и метрики принимаются на /api/agent/logs и /api/agent/metrics, heartbeat — на /api/agent/heartbeat.

OTLP ingestion

Бэкенд принимает OTLP/HTTP/JSON напрямую, без агента — например из serverless-сред. Авторизация тем же agent token:

Метод	Путь	Успешный ответ	Примечание
POST	/otlp/v1/metrics	202 Accepted	конвертируется во внутренний формат метрик
POST	/otlp/v1/logs	202 Accepted	конвертируется во внутренний формат логов
POST	/otlp/v1/traces	202 Accepted	traces принимаются и отбрасываются — трейсинг не реализован

Коды ошибок и реакция агента

HTTP	error code	Причина	Реакция агента
401	invalid_agent_token	токен невалиден или отозван	останов процесса с exit 77; нужен новый токен
401	minimum_version_required	версия агента ниже серверного minimumVersion	принудительное автообновление даже при FLAREE_AGENT_AUTO_UPDATE=false; если обновиться не удалось — exit 78
403	—	логи или метрики недоступны на тарифе	батч не отправляется повторно
429	quota_exceeded	превышена квота тарифа	пауза до Retry-After; заголовок приоритетен как authoritative backoff, reset_at из тела — справочное; данные остаются в буфере
5xx	—	временный сбой бэкенда	экспоненциальный backoff, батчи остаются в буфере до восстановления

Формат тела ошибки

Ответ 429 quota_exceeded содержит и заголовок, и тело:

{
  "error": "quota_exceeded",
  "reset_at": "2026-07-16T12:00:00Z",
  "retry_after_sec": 300
}

• reset_at — UTC-момент, когда квота обновится.
• retry_after_sec дублирует заголовок Retry-After; при расхождении заголовок приоритетен.

Ошибки 401/404 возвращают только код: { "error": "invalid_agent_token" }, { "error": "agent_not_found" }.

Связанные страницы

• Концепция: квоты и retention
• Концепция: агент
• Troubleshooting: 429 quota_exceeded