Referencia REST API

El manager expone una única REST API rooteada en /api. La SPA en web/ la llama; puedes llamarla directamente con cualquier cliente HTTP. No hay GraphQL, no hay gRPC para tráfico de aplicación (gRPC solo se usa para el túnel geminio, interno al manager).

Esta página es un catálogo de rutas, no una especificación swagger escrita a mano. Fuente de verdad: cmd/ongrid/main.go (los mounts chi.Router) y internal/manager/server/*/http.go (los handlers por-BC). Click al handler para los campos exactos de struct request/response.

Convenciones

• Base path: cada ruta tiene prefijo /api. Así GET /v1/edges se alcanza en https://<manager>/api/v1/edges.
• Versionado: todas las rutas están bajo /v1/. No hay /v2/. Cambios incompatibles hacia atrás se distribuyen detrás de feature flags o nuevas rutas.
• Auth: bearer JWT en Authorization: Bearer .... Las rutas públicas (login, refresh, register, webhooks IM, probe auth_request de Prometheus) saltean el middleware. Listadas en la tabla "Public" abajo.
• Roles: admin, user, viewer. Las rutas de escritura requieren admin (o la acción casbin relevante como edge:* / write); las rutas de lectura aceptan cualquier rol autenticado. viewer puede chatear pero el toolbag del agente se filtra a ClassSafe. Ver ADR-022 three-role RBAC.
• Errores: JSON {"error":"code","message":"human text"}. Los códigos son enums estables (not_found, invalid_argument, unauthorized, forbidden, conflict).
• Content type: cada request y response es application/json salvo que se note explícitamente (chat streamed es SSE, ingest de log/traza es OTLP-protobuf o Loki-JSON).

Rutas públicas (sin auth)

Método	Path	Propósito
GET	/healthz	probe de liveness
GET	/readyz	probe de readiness
GET	/internal/auth/dataplane-verify	probe auth_request de nginx para ingest de log/traza
POST	/api/v1/auth/login	intercambia email+password por JWT
POST	/api/v1/auth/refresh	intercambia refresh token por un access token fresco
POST	/api/v1/auth/register	self-registration (gateado por config)
GET	/api/v1/prometheus/auth	probe auth_request de nginx para el embed de Grafana
POST	/api/v1/im/feishu/events	callback entrante de Feishu/Lark; la firma webhook es la auth

Rutas autenticadas

iam (usuarios, orgs, sesiones)

Método	Path	Rol	Fuente
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	listar usuarios
POST	/v1/users	admin	crear usuario
PATCH	/v1/users/{id}	admin	actualizar usuario (nombre, email)
PATCH	/v1/users/{id}/password	self o admin	rotar password
PATCH	/v1/users/{id}/role	admin	cambiar rol (admin/user/viewer)
DELETE	/v1/users/{id}	admin	remover usuario
GET	/v1/orgs	any	listar orgs
POST	/v1/orgs	admin	crear org
PATCH	/v1/orgs/{id}	admin	actualizar org
DELETE	/v1/orgs/{id}	admin	remover org
GET	/v1/orgs/{id}/members	any	listar miembros
POST	/v1/orgs/{id}/members	admin	añadir miembro
PATCH	/v1/orgs/{id}/members/{user_id}	admin	cambiar rol de miembro
DELETE	/v1/orgs/{id}/members/{user_id}	admin	remover miembro

edge (el agente conectado al túnel)

Método	Path	Rol	Descripción
POST	/v1/edges	edge:*	crea edge, emite access+secret keys
GET	/v1/edges	any	listar edges
GET	/v1/edges/{id}	any	obtener detalle del edge
DELETE	/v1/edges/{id}	edge:*	borrar edge
POST	/v1/edges/{id}/rotate-secret	edge:*	rotar la secret key
POST	/v1/edges/{id}/upgrade	edge:*	disparar upgrade remoto del agente con URL+sha256 explícitos
POST	/v1/edges/{id}/upgrade-package	edge:*	upgrade de bundle de un clic (ADR-024)
GET	/v1/edges/{id}/processes	any	lista de procesos read-only (RPC on-demand)
GET	/v1/edges/{id}/plugins	any	listar plugins configurados + vivos del edge (con health)
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	habilitar/deshabilitar + tunear un plugin
GET	/v1/integrations/plugin-counts	any	counts globales de plugin enable/disable (para el tile de homepage)

device (entidad host, desacoplada del estado del túnel)

Método	Path	Rol	Descripción
GET	/v1/devices	any	listar host devices
GET	/v1/devices/{id}	any	obtener detalle del device
PATCH	/v1/devices/{id}	device:*	actualizar nombre de display, tags
DELETE	/v1/devices/{id}	device:*	remover device
PATCH	/v1/devices/{id}/roles	device:*	asignar roles (db, web, cache...)
GET	/v1/devices/{id}/edges	any	edges representando actualmente este device
GET	/v1/devices/{device_id}/shell	webshell	abrir un stream WebSSH (upgrade de websocket)

topology (CMDB tipada)

Método	Path	Rol	Descripción
GET	/v1/topology/node-types	any	listar schemas de node-type
POST	/v1/topology/node-types	topology:*	crear node type
GET	/v1/topology/node-types/{name}	any	obtener un node type
DELETE	/v1/topology/node-types/{name}	topology:*	remover node type
GET	/v1/topology/nodes	any	listar nodos (filtro por type, tag)
POST	/v1/topology/nodes	topology:*	crear nodo
GET	/v1/topology/nodes/{id}	any	obtener nodo
PATCH	/v1/topology/nodes/{id}	topology:*	actualizar nodo
DELETE	/v1/topology/nodes/{id}	topology:*	remover nodo
GET	/v1/topology/relation-types	any	listar schemas de relation-type
POST	/v1/topology/relation-types	topology:*	crear relation type
GET	/v1/topology/relation-types/{name}	any	obtener un relation type
DELETE	/v1/topology/relation-types/{name}	topology:*	remover relation type
GET	/v1/topology/relations	any	listar edges (relaciones)
POST	/v1/topology/relations	topology:*	crear relación
GET	/v1/topology/relations/{id}	any	obtener relación
PATCH	/v1/topology/relations/{id}	topology:*	actualizar relación
DELETE	/v1/topology/relations/{id}	topology:*	remover relación

alert (reglas, incidentes, canales)

Método	Path	Rol	Descripción
GET	/v1/alert-rules	any	listar reglas
POST	/v1/alert-rules	alert:*	crear regla
GET	/v1/alert-rules/{id}	any	obtener regla
PUT	/v1/alert-rules/{id}	alert:*	reemplazar regla
DELETE	/v1/alert-rules/{id}	alert:*	remover regla
POST	/v1/alert-rules/{id}/enabled	alert:*	flippear flag enabled
POST	/v1/alert-rules/preview	alert:*	dry-run una definición de regla contra data actual
GET	/v1/alerts/incidents	any	listar incidentes (filtros: status, severity, scope)
GET	/v1/alerts/incidents/{id}	any	obtener incidente
GET	/v1/alerts/incidents/{id}/events	any	timeline de eventos
POST	/v1/alerts/incidents/{id}/ack	any	acknowledge
POST	/v1/alerts/incidents/{id}/resolve	any	marcar resuelto
POST	/v1/alerts/incidents/{id}/silence	any	silenciar por N horas
GET	/v1/alerts/incidents/{id}/investigation	any	obtener el informe de investigación generado por IA
POST	/v1/alerts/incidents/{id}/investigation	any	disparar o re-ejecutar la investigación
GET	/v1/alerts/runtime-info	any	pace del evaluator + stats del último ciclo
GET	/v1/notification-channels	any	listar canales
POST	/v1/notification-channels	channel:*	crear canal
GET	/v1/notification-channels/{id}	any	obtener canal
PUT	/v1/notification-channels/{id}	channel:*	reemplazar canal
DELETE	/v1/notification-channels/{id}	channel:*	remover canal
POST	/v1/notification-channels/{id}/test	channel:*	enviar una notificación sintética

Ver Esquema de reglas de alerta para la forma JSON de una regla.

aiops (chat, agentes, modelos)

Método	Path	Rol	Descripción
GET	/v1/agents	any	listar personas de agente
GET	/v1/agents/{name}	any	obtener detalle de persona
DELETE	/v1/agents/{name}	agent:*	borrar una persona built-in / on-disk (raro; usualmente solo custom es borrable)
POST	/v1/agents/custom	agent:*	crear una persona definida por usuario
PATCH	/v1/agents/custom/{name}	agent:*	actualizar persona de usuario
DELETE	/v1/agents/custom/{name}	agent:*	borrar persona de usuario
GET	/v1/chat/sessions	any	listar sesiones
POST	/v1/chat/sessions	any	crear sesión
PATCH	/v1/chat/sessions/{id}	any	renombrar / taguear una sesión
DELETE	/v1/chat/sessions/{id}	any	borrar sesión
GET	/v1/chat/sessions/{id}/messages	any	historia de mensajes
POST	/v1/chat/sessions/{id}/messages	any	enviar un mensaje (no-streaming, devuelve respuesta final)
POST	/v1/chat/sessions/{id}/messages/stream	any	enviar un mensaje (stream SSE de eventos token + tool-call)
GET	/v1/aiops/models	any	providers + modelos disponibles (gateado por API keys configuradas)
POST	/v1/aiops/query-translate	any	composición LLM-asistida de PromQL / LogQL / TraceQL
GET	/v1/aiops/mentions/search	any	autocompletado para menciones @edge, @device, @dashboard
GET	/v1/usage/today	any	uso de tokens para el UTC-día actual

Ver Formato de persona de agente para la forma del frontmatter markdown.

knowledge (RAG, vault, repos, uploads)

Método	Path	Rol	Descripción
GET	/v1/knowledge/docs	any	listar documentos (árbol)
POST	/v1/knowledge/docs	knowledge:*	crear documento
GET	/v1/knowledge/docs/{id}	any	obtener documento
PATCH	/v1/knowledge/docs/{id}	knowledge:*	editar cuerpo del documento
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	mover a otro path
DELETE	/v1/knowledge/docs/{id}	knowledge:*	remover documento
GET	/v1/knowledge/paths	any	listar nodos de path (para el árbol)
GET	/v1/knowledge/repos	any	listar repos Git
POST	/v1/knowledge/repos	knowledge:*	registrar un repo
DELETE	/v1/knowledge/repos/{id}	knowledge:*	remover repo
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	disparar un re-sync
POST	/v1/knowledge/upload	knowledge:*	upload .md / .txt / .pdf / .docx (parseado vía docextract)
GET	/v1/knowledge/search	any	query RAG (devuelve chunks + scores)
POST	/v1/knowledge/vault/sync	knowledge:*	re-pull del vault integrado desde GitHub
GET	/v1/knowledge/ssh-identities	knowledge:*	listar SSH keys para auth de Git
POST	/v1/knowledge/ssh-identities	knowledge:*	registrar una SSH key existente
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	generar un nuevo keypair (la private key nunca sale del servidor)
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	editar identidad (nombre, comment)
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	remover identidad

skill (introspección del toolbag)

Método	Path	Rol	Descripción
GET	/v1/skills	any	listar skills (manager-scope + edge-scope)
GET	/v1/skills/{key}	any	obtener detalle de skill (schema, description, scope, class)
POST	/v1/skills/{key}/execute	skill:*	ejecución directa de skill (testing / debugging)

Ver Skill manifest para la forma de skill.json en disco.

logs / traces (proxies read-only)

Método	Path	Rol	Descripción
GET	/v1/logs/query_range	any	LogQL query_range proxied
GET	/v1/logs/labels	any	label-names proxied
GET	/v1/logs/labels/{name}/values	any	label-values proxied
GET	/v1/traces/search	any	TraceQL /api/search proxied
GET	/v1/traces/{trace_id}	any	una traza por ID
GET	/v1/traces/tags/{tag}/values	any	/api/search/tag/.../values proxied

monitor (dashboards / paneles)

Método	Path	Rol	Descripción
GET	/v1/monitor/panels	any	listar paneles
POST	/v1/monitor/panels	monitor:*	crear panel
PATCH	/v1/monitor/panels/{id}	monitor:*	editar panel
DELETE	/v1/monitor/panels/{id}	monitor:*	remover panel
GET	/v1/observability/dashboards/{uid}	any	JSON de dashboard Grafana listo para render

metric (snapshot de métrica por-edge)

Método	Path	Rol	Descripción
GET	/v1/edges/{id}/metrics	any	snapshot más reciente del conjunto cerrado de métricas de host

prometheus (admin)

Método	Path	Rol	Descripción
POST	/v1/prometheus/launch	admin	(re-)lanzar el Prometheus embedded
POST	/v1/prometheus/query_range	any	query_range cara al LLM-tool (devuelve matrix normalizada)

imbridge (superficies de chat — Slack / Telegram / Lark / DingTalk / WeCom)

Método	Path	Rol	Descripción
GET	/v1/im/apps	any	listar apps IM conectadas
POST	/v1/im/apps	im:*	registrar app IM
GET	/v1/im/apps/{id}	any	obtener app
PUT	/v1/im/apps/{id}	im:*	actualizar app
DELETE	/v1/im/apps/{id}	im:*	remover app
POST	/v1/im/apps/{id}/reveal	admin	revelar secrets enmascarados

marketplace (skill packs)

Método	Path	Rol	Descripción
GET	/v1/marketplace/registries	any	listar registries configurados
GET	/v1/marketplace/installed	any	listar packs instalados
POST	/v1/marketplace/install	marketplace:*	instalar pack desde un registry
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	desinstalar pack

setting (system settings: integraciones, defaults, secrets)

Método	Path	Rol	Descripción
GET	/v1/system-settings	any	listar settings visibles
PUT	/v1/system-settings/{category}/{key}	admin	upsert setting
DELETE	/v1/system-settings/{category}/{key}	admin	remover setting
GET	/v1/system-settings/{category}/{key}/reveal	admin	revelar secret enmascarado

integration (tests de conectividad)

Método	Path	Rol	Descripción
POST	/v1/integrations/grafana/sync	admin	sincronizar dashboards + datasources
POST	/v1/integrations/grafana/test	admin	testear conexión Grafana
POST	/v1/integrations/llm/invalidate	admin	invalidar cliente LLM cacheado (fuerza re-lectura de API keys)
POST	/v1/integrations/loki/test	admin	testear conexión Loki
POST	/v1/integrations/prom/test	admin	testear conexión Prometheus
POST	/v1/integrations/tempo/test	admin	testear conexión Tempo
POST	/v1/integrations/websearch/test	admin	testear backend SearXNG / web-search

webshell (shell interactivo sobre el túnel)

Método	Path	Rol	Descripción
GET	/v1/devices/{device_id}/shell	webshell	abrir stream SSH upgraded a WebSocket
GET	/v1/webshell/sessions	any	listar sesiones activas
DELETE	/v1/webshell/sessions/{id}	webshell	matar una sesión

audit (admin log)

Método	Path	Rol	Descripción
GET	/v1/admin/audit-logs	admin	trail de audit tenant-wide (HLD-010)

Paginación

Los endpoints de lista usan cursors opacos:

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

La respuesta lleva {"items":[...], "next_cursor":"...", "total":...}. next_cursor está vacío en la última página.

Rate limits

No hay rate limits globales en el build open-source. El gate de budget LLM (ONGRID_LLM_DAILY_TOKEN_LIMIT) acota el tráfico de chat — todo otro endpoint depende de lo que pongas delante del manager (nginx, tu propio gateway).

Versionado

GET /v1/version devuelve {"manager_version":"vX.Y.Z"}. La SPA lee esto y flaggea edges cuya versión de agente drifta del manager. Úsalo para tooling de upgrade.

Ver también

• Variables de entorno — qué controla el comportamiento de la API.
• Esquema de reglas de alerta — body de request para /v1/alert-rules.
• Skill manifest — body de request para /v1/skills e install de marketplace.
• Formato de persona de agente — body de request para /v1/agents/custom.