Referência da REST API

O manager expõe uma única REST API com raiz em /api. O SPA em web/ a chama; você pode chamar diretamente com qualquer client HTTP. Não há GraphQL, sem gRPC para tráfego de aplicação (gRPC só é usado para o tunnel geminio, interno ao manager).

Esta página é um catálogo de rotas, não um spec swagger escrito à mão. Fonte de verdade: cmd/ongrid/main.go (os mounts chi.Router) e internal/manager/server/*/http.go (os handlers por-BC). Clique no handler para os campos exatos de struct de request/response.

Convenções

• Base path: cada rota é prefixada /api. Então GET /v1/edges é alcançado em https://<manager>/api/v1/edges.
• Versionamento: todas as rotas estão sob /v1/. Não há /v2/. Mudanças incompatíveis distribuem atrás de feature flags ou novas rotas.
• Auth: bearer JWT em Authorization: Bearer .... Rotas públicas (login, refresh, register, webhooks IM, probe auth_request do Prometheus) pulam o middleware. Listadas na tabela "Públicas" abaixo.
• Roles: admin, user, viewer. Rotas write exigem admin (ou a ação casbin relevante como edge:* / write); rotas read aceitam qualquer role autenticada. viewer pode chat mas a toolbag do agent é filtrada a ClassSafe. Veja RBAC de três roles do ADR-022.
• Erros: JSON {"error":"code","message":"human text"}. Codes são enums estáveis (not_found, invalid_argument, unauthorized, forbidden, conflict).
• Content type: cada request e response é application/json a menos que explicitamente notado (chat streamed é SSE, ingest de log/trace é OTLP-protobuf ou Loki-JSON).

Rotas públicas (sem auth)

Método	Path	Propósito
GET	/healthz	probe de liveness
GET	/readyz	probe de readiness
GET	/internal/auth/dataplane-verify	probe nginx auth_request para ingest de log/trace
POST	/api/v1/auth/login	troca email+senha por JWT
POST	/api/v1/auth/refresh	troca refresh token por um access token novo
POST	/api/v1/auth/register	auto-registro (gateado por config)
GET	/api/v1/prometheus/auth	probe nginx auth_request para o embed Grafana
POST	/api/v1/im/feishu/events	callback inbound Feishu/Lark; a assinatura do webhook é a auth

Rotas autenticadas

iam (users, orgs, sessions)

Método	Path	Role	Fonte
GET	/v1/version	qualquer	cmd/ongrid/main.go (inline)
GET	/v1/me	qualquer	internal/iam/server/http.go
GET	/v1/self	qualquer	internal/iam/server/http.go
GET	/v1/users	qualquer	lista users
POST	/v1/users	admin	cria user
PATCH	/v1/users/{id}	admin	atualiza user (name, email)
PATCH	/v1/users/{id}/password	self ou admin	rotaciona senha
PATCH	/v1/users/{id}/role	admin	muda role (admin/user/viewer)
DELETE	/v1/users/{id}	admin	remove user
GET	/v1/orgs	qualquer	lista orgs
POST	/v1/orgs	admin	cria org
PATCH	/v1/orgs/{id}	admin	atualiza org
DELETE	/v1/orgs/{id}	admin	remove org
GET	/v1/orgs/{id}/members	qualquer	lista members
POST	/v1/orgs/{id}/members	admin	adiciona member
PATCH	/v1/orgs/{id}/members/{user_id}	admin	muda role do member
DELETE	/v1/orgs/{id}/members/{user_id}	admin	remove member

edge (o agent conectado ao tunnel)

Método	Path	Role	Descrição
POST	/v1/edges	edge:*	cria edge, emite access+secret keys
GET	/v1/edges	qualquer	lista edges
GET	/v1/edges/{id}	qualquer	pega detalhe do edge
DELETE	/v1/edges/{id}	edge:*	deleta edge
POST	/v1/edges/{id}/rotate-secret	edge:*	rotaciona a secret key
POST	/v1/edges/{id}/upgrade	edge:*	dispara upgrade remoto do agent com URL+sha256 explícito
POST	/v1/edges/{id}/upgrade-package	edge:*	upgrade one-click de bundle (ADR-024)
GET	/v1/edges/{id}/processes	qualquer	lista de processos read-only (RPC on-demand)
GET	/v1/edges/{id}/plugins	qualquer	lista plugins configurados + vivos do edge (com health)
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	habilita/desabilita + tune de um plugin
GET	/v1/integrations/plugin-counts	qualquer	contagens globais de plugin habilitado/desabilitado (para o tile da homepage)

device (entidade de host, desacoplada do estado do tunnel)

Método	Path	Role	Descrição
GET	/v1/devices	qualquer	lista host devices
GET	/v1/devices/{id}	qualquer	pega detalhe do device
PATCH	/v1/devices/{id}	device:*	atualiza nome de display, tags
DELETE	/v1/devices/{id}	device:*	remove device
PATCH	/v1/devices/{id}/roles	device:*	atribui roles (db, web, cache...)
GET	/v1/devices/{id}/edges	qualquer	edges atualmente representando esse device
GET	/v1/devices/{device_id}/shell	webshell	abre um stream WebSSH (upgrade websocket)

topology (CMDB tipado)

Método	Path	Role	Descrição
GET	/v1/topology/node-types	qualquer	lista schemas de node-type
POST	/v1/topology/node-types	topology:*	cria node type
GET	/v1/topology/node-types/{name}	qualquer	pega um node type
DELETE	/v1/topology/node-types/{name}	topology:*	remove node type
GET	/v1/topology/nodes	qualquer	lista nós (filtro por tipo, tag)
POST	/v1/topology/nodes	topology:*	cria nó
GET	/v1/topology/nodes/{id}	qualquer	pega nó
PATCH	/v1/topology/nodes/{id}	topology:*	atualiza nó
DELETE	/v1/topology/nodes/{id}	topology:*	remove nó
GET	/v1/topology/relation-types	qualquer	lista schemas de relation-type
POST	/v1/topology/relation-types	topology:*	cria relation type
GET	/v1/topology/relation-types/{name}	qualquer	pega um relation type
DELETE	/v1/topology/relation-types/{name}	topology:*	remove relation type
GET	/v1/topology/relations	qualquer	lista arestas (relations)
POST	/v1/topology/relations	topology:*	cria relation
GET	/v1/topology/relations/{id}	qualquer	pega relation
PATCH	/v1/topology/relations/{id}	topology:*	atualiza relation
DELETE	/v1/topology/relations/{id}	topology:*	remove relation

alert (rules, incidents, channels)

Método	Path	Role	Descrição
GET	/v1/alert-rules	qualquer	lista rules
POST	/v1/alert-rules	alert:*	cria rule
GET	/v1/alert-rules/{id}	qualquer	pega rule
PUT	/v1/alert-rules/{id}	alert:*	substitui rule
DELETE	/v1/alert-rules/{id}	alert:*	remove rule
POST	/v1/alert-rules/{id}/enabled	alert:*	vira flag enabled
POST	/v1/alert-rules/preview	alert:*	dry-run de uma definição de rule contra dado atual
GET	/v1/alerts/incidents	qualquer	lista incidents (filtros: status, severity, scope)
GET	/v1/alerts/incidents/{id}	qualquer	pega incident
GET	/v1/alerts/incidents/{id}/events	qualquer	timeline de eventos
POST	/v1/alerts/incidents/{id}/ack	qualquer	acknowledge
POST	/v1/alerts/incidents/{id}/resolve	qualquer	marca resolved
POST	/v1/alerts/incidents/{id}/silence	qualquer	silencia por N horas
GET	/v1/alerts/incidents/{id}/investigation	qualquer	pega o report de investigação gerado por IA
POST	/v1/alerts/incidents/{id}/investigation	qualquer	dispara ou re-roda a investigação
GET	/v1/alerts/runtime-info	qualquer	pace do evaluator + stats do último ciclo
GET	/v1/notification-channels	qualquer	lista canais
POST	/v1/notification-channels	channel:*	cria canal
GET	/v1/notification-channels/{id}	qualquer	pega canal
PUT	/v1/notification-channels/{id}	channel:*	substitui canal
DELETE	/v1/notification-channels/{id}	channel:*	remove canal
POST	/v1/notification-channels/{id}/test	channel:*	envia notificação sintética

Veja Schema de alert rule para o formato JSON de uma rule.

aiops (chat, agents, models)

Método	Path	Role	Descrição
GET	/v1/agents	qualquer	lista personas de agent
GET	/v1/agents/{name}	qualquer	pega detalhe da persona
DELETE	/v1/agents/{name}	agent:*	deleta uma persona built-in / disk (raro; geralmente só custom deletável)
POST	/v1/agents/custom	agent:*	cria uma persona definida pelo usuário
PATCH	/v1/agents/custom/{name}	agent:*	atualiza user persona
DELETE	/v1/agents/custom/{name}	agent:*	deleta user persona
GET	/v1/chat/sessions	qualquer	lista sessões
POST	/v1/chat/sessions	qualquer	cria sessão
PATCH	/v1/chat/sessions/{id}	qualquer	renomeia / tagueia uma sessão
DELETE	/v1/chat/sessions/{id}	qualquer	deleta sessão
GET	/v1/chat/sessions/{id}/messages	qualquer	histórico de mensagens
POST	/v1/chat/sessions/{id}/messages	qualquer	envia uma mensagem (não-streaming, retorna reply final)
POST	/v1/chat/sessions/{id}/messages/stream	qualquer	envia uma mensagem (stream SSE de eventos token + tool-call)
GET	/v1/aiops/models	qualquer	providers + models disponíveis (gateado por API keys configuradas)
POST	/v1/aiops/query-translate	qualquer	composição PromQL / LogQL / TraceQL assistida por LLM
GET	/v1/aiops/mentions/search	qualquer	autocomplete para menções @edge, @device, @dashboard
GET	/v1/usage/today	qualquer	uso de token para o dia UTC corrente

Veja Formato de persona de agent para o formato do frontmatter markdown.

knowledge (RAG, vault, repos, uploads)

Método	Path	Role	Descrição
GET	/v1/knowledge/docs	qualquer	lista documentos (árvore)
POST	/v1/knowledge/docs	knowledge:*	cria documento
GET	/v1/knowledge/docs/{id}	qualquer	pega documento
PATCH	/v1/knowledge/docs/{id}	knowledge:*	edita corpo do documento
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	move para outro path
DELETE	/v1/knowledge/docs/{id}	knowledge:*	remove documento
GET	/v1/knowledge/paths	qualquer	lista nós de path (para a árvore)
GET	/v1/knowledge/repos	qualquer	lista repos Git
POST	/v1/knowledge/repos	knowledge:*	registra um repo
DELETE	/v1/knowledge/repos/{id}	knowledge:*	remove repo
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	dispara um re-sync
POST	/v1/knowledge/upload	knowledge:*	upload .md / .txt / .pdf / .docx (parseado via docextract)
GET	/v1/knowledge/search	qualquer	query RAG (retorna chunks + scores)
POST	/v1/knowledge/vault/sync	knowledge:*	re-puxa vault built-in do GitHub
GET	/v1/knowledge/ssh-identities	knowledge:*	lista chaves SSH para auth Git
POST	/v1/knowledge/ssh-identities	knowledge:*	registra uma chave SSH existente
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	gera um novo keypair (chave privada nunca sai do server)
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	edita identity (name, comment)
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	remove identity

skill (introspecção de toolbag)

Método	Path	Role	Descrição
GET	/v1/skills	qualquer	lista skills (escopo manager + escopo edge)
GET	/v1/skills/{key}	qualquer	pega detalhe da skill (schema, descrição, scope, class)
POST	/v1/skills/{key}/execute	skill:*	execução direta de skill (testing / debugging)

Veja Manifesto de skill para o formato skill.json on-disk.

logs / traces (proxies read-only)

Método	Path	Role	Descrição
GET	/v1/logs/query_range	qualquer	LogQL query_range proxiado
GET	/v1/logs/labels	qualquer	label-names proxiado
GET	/v1/logs/labels/{name}/values	qualquer	label-values proxiado
GET	/v1/traces/search	qualquer	TraceQL /api/search proxiado
GET	/v1/traces/{trace_id}	qualquer	um trace por ID
GET	/v1/traces/tags/{tag}/values	qualquer	/api/search/tag/.../values proxiado

monitor (dashboards / painéis)

Método	Path	Role	Descrição
GET	/v1/monitor/panels	qualquer	lista painéis
POST	/v1/monitor/panels	monitor:*	cria painel
PATCH	/v1/monitor/panels/{id}	monitor:*	edita painel
DELETE	/v1/monitor/panels/{id}	monitor:*	remove painel
GET	/v1/observability/dashboards/{uid}	qualquer	JSON de dashboard Grafana pronto para render

metric (snapshot de métrica por-edge)

Método	Path	Role	Descrição
GET	/v1/edges/{id}/metrics	qualquer	último snapshot de métrica de host conjunto-fechado

prometheus (admin)

Método	Path	Role	Descrição
POST	/v1/prometheus/launch	admin	(re-)lança o Prometheus embarcado
POST	/v1/prometheus/query_range	qualquer	query_range voltado ao LLM-tool (retorna matriz normalizada)

imbridge (superfícies de chat — Slack / Telegram / Lark / DingTalk / WeCom)

Método	Path	Role	Descrição
GET	/v1/im/apps	qualquer	lista apps IM conectados
POST	/v1/im/apps	im:*	registra app IM
GET	/v1/im/apps/{id}	qualquer	pega app
PUT	/v1/im/apps/{id}	im:*	atualiza app
DELETE	/v1/im/apps/{id}	im:*	remove app
POST	/v1/im/apps/{id}/reveal	admin	revela secrets mascarados

marketplace (skill packs)

Método	Path	Role	Descrição
GET	/v1/marketplace/registries	qualquer	lista registries configuradas
GET	/v1/marketplace/installed	qualquer	lista packs instalados
POST	/v1/marketplace/install	marketplace:*	instala pack de um registry
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	desinstala pack

setting (settings do sistema: integrações, defaults, secrets)

Método	Path	Role	Descrição
GET	/v1/system-settings	qualquer	lista settings visíveis
PUT	/v1/system-settings/{category}/{key}	admin	upsert de setting
DELETE	/v1/system-settings/{category}/{key}	admin	remove setting
GET	/v1/system-settings/{category}/{key}/reveal	admin	revela secret mascarado

integration (testes de conectividade)

Método	Path	Role	Descrição
POST	/v1/integrations/grafana/sync	admin	sincroniza dashboards + datasources
POST	/v1/integrations/grafana/test	admin	testa conexão Grafana
POST	/v1/integrations/llm/invalidate	admin	invalida client LLM cacheado (força re-leitura de API keys)
POST	/v1/integrations/loki/test	admin	testa conexão Loki
POST	/v1/integrations/prom/test	admin	testa conexão Prometheus
POST	/v1/integrations/tempo/test	admin	testa conexão Tempo
POST	/v1/integrations/websearch/test	admin	testa backend SearXNG / web-search

webshell (shell interativo sobre o tunnel)

Método	Path	Role	Descrição
GET	/v1/devices/{device_id}/shell	webshell	abre stream SSH upgraded em WebSocket
GET	/v1/webshell/sessions	qualquer	lista sessões ativas
DELETE	/v1/webshell/sessions/{id}	webshell	mata uma sessão

audit (log de admin)

Método	Path	Role	Descrição
GET	/v1/admin/audit-logs	admin	audit trail tenant-wide (HLD-010)

Paginação

Endpoints de lista usam cursores opacos:

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

A resposta carrega {"items":[...], "next_cursor":"...", "total":...}. next_cursor é vazio na última página.

Rate limits

Não há rate limits globais no build open-source. O gate de budget LLM (ONGRID_LLM_DAILY_TOKEN_LIMIT) limita tráfego de chat — todo outro endpoint depende do que você coloca na frente do manager (nginx, seu próprio gateway).

Versionamento

GET /v1/version retorna {"manager_version":"vX.Y.Z"}. O SPA lê isso e flagga edges cuja versão de agent drifta do manager. Use para tooling de upgrade.

Veja também

• Variáveis de ambiente — o que controla o comportamento da API.
• Schema de alert rule — body de request para /v1/alert-rules.
• Manifesto de skill — body de request para /v1/skills e instalação do marketplace.
• Formato de persona de agent — body de request para /v1/agents/custom.