Skip to main content

API agent и ingestion endpoints

info

Перевод в процессе / Translation in progress. See русская версия.

Публичное API Flaree состоит из двух групп эндпоинтов: agent API (регистрация, конфигурация, checkins, heartbeat, инвентаризация) и ingestion API (приём логов, метрик и трейсов, включая OTLP-совместимые маршруты). Все запросы идут egress-only от агента к бэкенду по HTTPS и авторизуются заголовком X-Flaree-Token: <agent-token> либо эквивалентным Authorization: Bearer <agent-token>.

Agent API​

МетодПутьАутентификацияТелоОтветОшибки
POST/api/agent/registerX-Flaree-Tokenapplication/json RegisterAgentRequestapplication/json RegisterAgentResponse401 invalid_agent_token
GET/api/agent/configX-Flaree-Token—application/json AgentConfigResponse401 minimum_version_required
POST/api/agent/checkinsX-Flaree-Tokenapplication/json CheckinsBatch204 No Content429 quota_exceeded
POST/api/agent/heartbeatX-Flaree-Tokenapplication/json HeartbeatRequestapplication/json HeartbeatResponse401 invalid_agent_token
POST/api/agent/inventoryX-Flaree-Tokenapplication/json InventoryPayload204 No Content—

Ingestion endpoints​

МетодПутьАутентификацияТелоОтветОшибки
POST/ingest/logsX-Flaree-Tokenapplication/json LogsBatch204 No Content429 quota_exceeded, 401 invalid_agent_token
POST/ingest/metricsX-Flaree-Tokenapplication/json MetricsBatch204 No Content429 quota_exceeded
POST/ingest/heartbeatX-Flaree-Tokenapplication/json HeartbeatBatch204 No Content—
POST/otlp/v1/metricsX-Flaree-Tokenapplication/json OTLP204 No Content429 quota_exceeded
POST/otlp/v1/logsX-Flaree-Tokenapplication/json OTLP204 No Content429 quota_exceeded
POST/otlp/v1/tracesX-Flaree-Tokenapplication/json OTLP204 No Content (принят, но span-ы могут не отображаться)429 quota_exceeded

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

HTTPerror codeПричинаРеакция агента
401invalid_agent_tokenтокен невалиден или отозваностановка отправки, статус surface-ится в следующем heartbeat
401minimum_version_requiredтребуется более новая версия агентатриггер auto-update через channel / min-version
429quota_exceededпревышена квота плана (логи, метрики или трейсы)honour заголовок Retry-After и поле reset_at в теле, буферизация в SQLite spool; при одновременном наличии Retry-After имеет приоритет как authoritative backoff
5xx(transport)временный сбой бэкендаexponential backoff с jitter, буферизация в SQLite spool

Формат ответа при ошибке​

{
  "error": "quota_exceeded",
  "message": "Workspace logs quota exceeded",
  "reset_at": "2026-05-10T12:00:00Z"
}

Поле reset_at присутствует только для ответов 429 quota_exceeded и означает момент, когда квота обновится. Для прочих ошибок (401, 5xx) тело содержит только error и message.

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