Справочник REST API

Manager выставляет единый REST API с корнем /api. SPA в web/ его вызывает; вы можете вызывать его напрямую любым HTTP-клиентом. Нет GraphQL, нет gRPC для трафика приложения (gRPC используется только для geminio-туннеля, внутри manager'а).

Эта страница — каталог маршрутов, не написанная вручную swagger-спецификация. Источник истины: cmd/ongrid/main.go (mounts chi.Router'а) и internal/manager/server/*/http.go (per-BC обработчики). Кликайте по handler'у для точных полей struct request/response.

Соглашения

• Базовый путь: каждый маршрут имеет префикс /api. Так что GET /v1/edges доступен по https://<manager>/api/v1/edges.
• Версионирование: все маршруты под /v1/. Нет /v2/. Несовместимые изменения едут за feature-флагами или новыми маршрутами.
• Auth: bearer JWT в Authorization: Bearer .... Публичные маршруты (login, refresh, register, IM webhooks, auth_request-проба Prometheus) пропускают middleware. Перечислены в таблице "Public" ниже.
• Роли: admin, user, viewer. Write-маршруты требуют admin (или соответствующего casbin-действия типа edge:* / write); read-маршруты принимают любую авторизованную роль. viewer может вести чат, но toolbag агента фильтруется до ClassSafe. См. ADR-022 three-role RBAC.
• Ошибки: JSON {"error":"code","message":"human text"}. Коды — стабильные enum'ы (not_found, invalid_argument, unauthorized, forbidden, conflict).
• Content type: каждый запрос и ответ — application/json, если явно не указано иное (streaming chat — SSE, ingest логов/трейсов — OTLP-protobuf или Loki-JSON).

Публичные маршруты (без auth)

Метод	Путь	Назначение
GET	/healthz	liveness-проба
GET	/readyz	readiness-проба
GET	/internal/auth/dataplane-verify	auth_request-проба nginx для ingest'а логов/трейсов
POST	/api/v1/auth/login	обмен email+пароль на JWT
POST	/api/v1/auth/refresh	обмен refresh-токена на новый access-токен
POST	/api/v1/auth/register	самостоятельная регистрация (гейтится конфигом)
GET	/api/v1/prometheus/auth	auth_request-проба nginx для Grafana embed
POST	/api/v1/im/feishu/events	входящий Feishu/Lark callback; auth — это webhook-подпись

Авторизованные маршруты

iam (пользователи, организации, сессии)

Метод	Путь	Роль	Источник
GET	/v1/version	any	cmd/ongrid/main.go (inline)
GET	/v1/me	any	internal/iam/server/http.go
GET	/v1/self	any	internal/iam/server/http.go
GET	/v1/users	any	список пользователей
POST	/v1/users	admin	создать пользователя
PATCH	/v1/users/{id}	admin	обновить пользователя (имя, email)
PATCH	/v1/users/{id}/password	self or admin	сменить пароль
PATCH	/v1/users/{id}/role	admin	сменить роль (admin/user/viewer)
DELETE	/v1/users/{id}	admin	удалить пользователя
GET	/v1/orgs	any	список организаций
POST	/v1/orgs	admin	создать организацию
PATCH	/v1/orgs/{id}	admin	обновить организацию
DELETE	/v1/orgs/{id}	admin	удалить организацию
GET	/v1/orgs/{id}/members	any	список участников
POST	/v1/orgs/{id}/members	admin	добавить участника
PATCH	/v1/orgs/{id}/members/{user_id}	admin	сменить роль участника
DELETE	/v1/orgs/{id}/members/{user_id}	admin	удалить участника

edge (агент, подключённый по туннелю)

Метод	Путь	Роль	Описание
POST	/v1/edges	edge:*	создать edge, выдаёт access+secret ключи
GET	/v1/edges	any	список edges
GET	/v1/edges/{id}	any	детали edge
DELETE	/v1/edges/{id}	edge:*	удалить edge
POST	/v1/edges/{id}/rotate-secret	edge:*	ротация secret-ключа
POST	/v1/edges/{id}/upgrade	edge:*	триггер удалённого апгрейда агента с явным URL+sha256
POST	/v1/edges/{id}/upgrade-package	edge:*	one-click bundle-апгрейд (ADR-024)
GET	/v1/edges/{id}/processes	any	read-only список процессов (on-demand RPC)
GET	/v1/edges/{id}/plugins	any	список настроенных + live плагинов edge (с health)
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	включить/выключить + настроить плагин
GET	/v1/integrations/plugin-counts	any	глобальные счётчики enable/disable плагинов (для плитки на главной)

device (host-сущность, отвязана от состояния туннеля)

Метод	Путь	Роль	Описание
GET	/v1/devices	any	список host-устройств
GET	/v1/devices/{id}	any	детали устройства
PATCH	/v1/devices/{id}	device:*	обновить отображаемое имя, теги
DELETE	/v1/devices/{id}	device:*	удалить устройство
PATCH	/v1/devices/{id}/roles	device:*	назначить роли (db, web, cache...)
GET	/v1/devices/{id}/edges	any	edges, представляющие это устройство сейчас
GET	/v1/devices/{device_id}/shell	webshell	открыть поток WebSSH (websocket upgrade)

topology (типизированная CMDB)

Метод	Путь	Роль	Описание
GET	/v1/topology/node-types	any	список схем типов узлов
POST	/v1/topology/node-types	topology:*	создать тип узла
GET	/v1/topology/node-types/{name}	any	получить один тип узла
DELETE	/v1/topology/node-types/{name}	topology:*	удалить тип узла
GET	/v1/topology/nodes	any	список узлов (фильтр по типу, тегу)
POST	/v1/topology/nodes	topology:*	создать узел
GET	/v1/topology/nodes/{id}	any	получить узел
PATCH	/v1/topology/nodes/{id}	topology:*	обновить узел
DELETE	/v1/topology/nodes/{id}	topology:*	удалить узел
GET	/v1/topology/relation-types	any	список схем типов связей
POST	/v1/topology/relation-types	topology:*	создать тип связи
GET	/v1/topology/relation-types/{name}	any	получить один тип связи
DELETE	/v1/topology/relation-types/{name}	topology:*	удалить тип связи
GET	/v1/topology/relations	any	список рёбер (связей)
POST	/v1/topology/relations	topology:*	создать связь
GET	/v1/topology/relations/{id}	any	получить связь
PATCH	/v1/topology/relations/{id}	topology:*	обновить связь
DELETE	/v1/topology/relations/{id}	topology:*	удалить связь

alert (правила, инциденты, каналы)

Метод	Путь	Роль	Описание
GET	/v1/alert-rules	any	список правил
POST	/v1/alert-rules	alert:*	создать правило
GET	/v1/alert-rules/{id}	any	получить правило
PUT	/v1/alert-rules/{id}	alert:*	заменить правило
DELETE	/v1/alert-rules/{id}	alert:*	удалить правило
POST	/v1/alert-rules/{id}/enabled	alert:*	переключить флаг enabled
POST	/v1/alert-rules/preview	alert:*	dry-run определения правила на текущих данных
GET	/v1/alerts/incidents	any	список инцидентов (фильтры: status, severity, scope)
GET	/v1/alerts/incidents/{id}	any	получить инцидент
GET	/v1/alerts/incidents/{id}/events	any	таймлайн событий
POST	/v1/alerts/incidents/{id}/ack	any	подтвердить (acknowledge)
POST	/v1/alerts/incidents/{id}/resolve	any	пометить как resolved
POST	/v1/alerts/incidents/{id}/silence	any	заглушить на N часов
GET	/v1/alerts/incidents/{id}/investigation	any	получить AI-сгенерированный investigation-отчёт
POST	/v1/alerts/incidents/{id}/investigation	any	запустить или перезапустить расследование
GET	/v1/alerts/runtime-info	any	темп evaluator'а + статистика последнего цикла
GET	/v1/notification-channels	any	список каналов
POST	/v1/notification-channels	channel:*	создать канал
GET	/v1/notification-channels/{id}	any	получить канал
PUT	/v1/notification-channels/{id}	channel:*	заменить канал
DELETE	/v1/notification-channels/{id}	channel:*	удалить канал
POST	/v1/notification-channels/{id}/test	channel:*	отправить синтетическое уведомление

См. схему правила алерта для JSON-формы правила.

aiops (chat, агенты, модели)

Метод	Путь	Роль	Описание
GET	/v1/agents	any	список personas агента
GET	/v1/agents/{name}	any	детали persona
DELETE	/v1/agents/{name}	agent:*	удалить встроенную / disk persona (редко; обычно удаляется только custom)
POST	/v1/agents/custom	agent:*	создать пользовательскую persona
PATCH	/v1/agents/custom/{name}	agent:*	обновить пользовательскую persona
DELETE	/v1/agents/custom/{name}	agent:*	удалить пользовательскую persona
GET	/v1/chat/sessions	any	список сессий
POST	/v1/chat/sessions	any	создать сессию
PATCH	/v1/chat/sessions/{id}	any	переименовать / отметить сессию тегом
DELETE	/v1/chat/sessions/{id}	any	удалить сессию
GET	/v1/chat/sessions/{id}/messages	any	история сообщений
POST	/v1/chat/sessions/{id}/messages	any	отправить сообщение (non-streaming, возвращает финальный ответ)
POST	/v1/chat/sessions/{id}/messages/stream	any	отправить сообщение (SSE-поток событий токенов + tool-call)
GET	/v1/aiops/models	any	доступные provider'ы + модели (гейтятся настроенными API-ключами)
POST	/v1/aiops/query-translate	any	LLM-assisted композиция PromQL / LogQL / TraceQL
GET	/v1/aiops/mentions/search	any	автодополнение для упоминаний @edge, @device, @dashboard
GET	/v1/usage/today	any	использование токенов за текущий UTC-день

См. формат persona агента для формы markdown frontmatter.

knowledge (RAG, vault, repos, uploads)

Метод	Путь	Роль	Описание
GET	/v1/knowledge/docs	any	список документов (tree)
POST	/v1/knowledge/docs	knowledge:*	создать документ
GET	/v1/knowledge/docs/{id}	any	получить документ
PATCH	/v1/knowledge/docs/{id}	knowledge:*	редактировать тело документа
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	переместить в другой путь
DELETE	/v1/knowledge/docs/{id}	knowledge:*	удалить документ
GET	/v1/knowledge/paths	any	список path-узлов (для дерева)
GET	/v1/knowledge/repos	any	список Git-репозиториев
POST	/v1/knowledge/repos	knowledge:*	зарегистрировать репозиторий
DELETE	/v1/knowledge/repos/{id}	knowledge:*	удалить репозиторий
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	запустить re-sync
POST	/v1/knowledge/upload	knowledge:*	загрузить .md / .txt / .pdf / .docx (парсится через docextract)
GET	/v1/knowledge/search	any	RAG-запрос (возвращает chunks + scores)
POST	/v1/knowledge/vault/sync	knowledge:*	заново подтянуть встроенный vault из GitHub
GET	/v1/knowledge/ssh-identities	knowledge:*	список SSH-ключей для Git auth
POST	/v1/knowledge/ssh-identities	knowledge:*	зарегистрировать существующий SSH-ключ
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	сгенерировать новую keypair (приватный ключ никогда не покидает сервер)
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	редактировать identity (имя, комментарий)
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	удалить identity

skill (интроспекция toolbag)

Метод	Путь	Роль	Описание
GET	/v1/skills	any	список скиллов (manager-scope + edge-scope)
GET	/v1/skills/{key}	any	детали скилла (схема, описание, scope, class)
POST	/v1/skills/{key}/execute	skill:*	прямое исполнение скилла (тестирование / отладка)

См. skill-манифест для формы on-disk skill.json.

logs / traces (read-only прокси)

Метод	Путь	Роль	Описание
GET	/v1/logs/query_range	any	проксированный LogQL query_range
GET	/v1/logs/labels	any	проксированные label-names
GET	/v1/logs/labels/{name}/values	any	проксированные label-values
GET	/v1/traces/search	any	проксированный TraceQL /api/search
GET	/v1/traces/{trace_id}	any	один trace по ID
GET	/v1/traces/tags/{tag}/values	any	проксированный /api/search/tag/.../values

monitor (дашборды / панели)

Метод	Путь	Роль	Описание
GET	/v1/monitor/panels	any	список панелей
POST	/v1/monitor/panels	monitor:*	создать панель
PATCH	/v1/monitor/panels/{id}	monitor:*	редактировать панель
DELETE	/v1/monitor/panels/{id}	monitor:*	удалить панель
GET	/v1/observability/dashboards/{uid}	any	готовый к рендеру JSON Grafana-дашборда

metric (snapshot метрик per-edge)

Метод	Путь	Роль	Описание
GET	/v1/edges/{id}/metrics	any	последний snapshot host-метрик из закрытого набора

prometheus (admin)

Метод	Путь	Роль	Описание
POST	/v1/prometheus/launch	admin	(пере)запустить встроенный Prometheus
POST	/v1/prometheus/query_range	any	LLM-tool-facing query_range (возвращает нормализованную матрицу)

imbridge (чат-поверхности — Slack / Telegram / Lark / DingTalk / WeCom)

Метод	Путь	Роль	Описание
GET	/v1/im/apps	any	список подключённых IM-приложений
POST	/v1/im/apps	im:*	зарегистрировать IM-приложение
GET	/v1/im/apps/{id}	any	получить приложение
PUT	/v1/im/apps/{id}	im:*	обновить приложение
DELETE	/v1/im/apps/{id}	im:*	удалить приложение
POST	/v1/im/apps/{id}/reveal	admin	раскрыть замаскированные секреты

marketplace (skill-паки)

Метод	Путь	Роль	Описание
GET	/v1/marketplace/registries	any	список настроенных registry
GET	/v1/marketplace/installed	any	список установленных паков
POST	/v1/marketplace/install	marketplace:*	установить пак из registry
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	удалить пак

setting (системные настройки: интеграции, дефолты, секреты)

Метод	Путь	Роль	Описание
GET	/v1/system-settings	any	список видимых настроек
PUT	/v1/system-settings/{category}/{key}	admin	upsert настройки
DELETE	/v1/system-settings/{category}/{key}	admin	удалить настройку
GET	/v1/system-settings/{category}/{key}/reveal	admin	раскрыть замаскированный секрет

integration (тесты подключений)

Метод	Путь	Роль	Описание
POST	/v1/integrations/grafana/sync	admin	синхронизация дашбордов + datasources
POST	/v1/integrations/grafana/test	admin	проверка подключения к Grafana
POST	/v1/integrations/llm/invalidate	admin	инвалидировать кешированного LLM-клиента (принудительно перечитать API-ключи)
POST	/v1/integrations/loki/test	admin	проверка подключения к Loki
POST	/v1/integrations/prom/test	admin	проверка подключения к Prometheus
POST	/v1/integrations/tempo/test	admin	проверка подключения к Tempo
POST	/v1/integrations/websearch/test	admin	проверка SearXNG / бэкенда web-search

webshell (интерактивный shell поверх туннеля)

Метод	Путь	Роль	Описание
GET	/v1/devices/{device_id}/shell	webshell	открыть SSH-поток с WebSocket-upgrade
GET	/v1/webshell/sessions	any	список активных сессий
DELETE	/v1/webshell/sessions/{id}	webshell	завершить сессию

audit (admin log)

Метод	Путь	Роль	Описание
GET	/v1/admin/audit-logs	admin	tenant-wide audit-trail (HLD-010)

Пагинация

List-эндпоинты используют непрозрачные курсоры:

GET /v1/edges?limit=50&cursor=eyJpZCI6MTAwMH0

Ответ несёт {"items":[...], "next_cursor":"...", "total":...}. next_cursor пуст на последней странице.

Rate limits

В open-source-сборке нет глобальных rate limit'ов. LLM-гейт бюджета (ONGRID_LLM_DAILY_TOKEN_LIMIT) ограничивает чат-трафик — каждый другой эндпоинт зависит от того, что вы поставили перед manager'ом (nginx, ваш собственный gateway).

Версионирование

GET /v1/version возвращает {"manager_version":"vX.Y.Z"}. SPA читает это и помечает edges, у которых версия агента дрейфит относительно manager'а. Используйте для апгрейд-тулинга.

См. также

• Environment-переменные — что управляет поведением API.
• Схема правила алерта — тело запроса для /v1/alert-rules.
• Skill-манифест — тело запроса для /v1/skills и установки из marketplace.
• Формат persona агента — тело запроса для /v1/agents/custom.