Référence API REST

Le manager expose une seule API REST racinée à /api. La SPA dans web/ l'appelle ; vous pouvez l'appeler directement avec n'importe quel client HTTP. Il n'y a pas de GraphQL, pas de gRPC pour le trafic applicatif (gRPC n'est utilisé que pour le tunnel geminio, interne au manager).

Cette page est un catalogue de routes, pas une spec swagger écrite à la main. Source de vérité : cmd/ongrid/main.go (les mounts chi.Router) et internal/manager/server/*/http.go (les handlers par BC). Cliquez vers le handler pour les champs exacts de struct requête/réponse.

Conventions

• Chemin de base : chaque route est préfixée /api. Donc GET /v1/edges est atteint à https://<manager>/api/v1/edges.
• Versioning : toutes les routes sont sous /v1/. Il n'y a pas de /v2/. Les changements rétro-incompatibles partent derrière des feature flags ou de nouvelles routes.
• Auth : JWT bearer dans Authorization: Bearer .... Les routes publiques (login, refresh, register, webhooks IM, sonde auth_request de Prometheus) sautent le middleware. Listées dans le tableau « Public » ci-dessous.
• Rôles : admin, user, viewer. Les routes write requièrent admin (ou l'action casbin pertinente comme edge:* / write) ; les routes read acceptent n'importe quel rôle authentifié. viewer peut chatter mais le sac d'outils de l'agent est filtré à ClassSafe. Voir RBAC à trois rôles ADR-022.
• Erreurs : JSON {"error":"code","message":"human text"}. Les codes sont des enums stables (not_found, invalid_argument, unauthorized, forbidden, conflict).
• Type de contenu : chaque requête et réponse est application/json sauf si explicitement noté (chat streamé est SSE, ingest log/trace est OTLP-protobuf ou Loki-JSON).

Routes publiques (pas d'auth)

Méthode	Chemin	Rôle
GET	/healthz	sonde de liveness
GET	/readyz	sonde de readiness
GET	/internal/auth/dataplane-verify	sonde auth_request nginx pour ingest log/trace
POST	/api/v1/auth/login	échange email+mot de passe contre JWT
POST	/api/v1/auth/refresh	échange refresh token contre access token frais
POST	/api/v1/auth/register	auto-enregistrement (gaté par config)
GET	/api/v1/prometheus/auth	sonde auth_request nginx pour l'embed Grafana
POST	/api/v1/im/feishu/events	callback Feishu/Lark entrant ; la signature de webhook est l'auth

Routes authentifiées

iam (utilisateurs, orgs, sessions)

Méthode	Chemin	Rôle	Source
GET	/v1/version	tous	cmd/ongrid/main.go (inline)
GET	/v1/me	tous	internal/iam/server/http.go
GET	/v1/self	tous	internal/iam/server/http.go
GET	/v1/users	tous	lister utilisateurs
POST	/v1/users	admin	créer utilisateur
PATCH	/v1/users/{id}	admin	mettre à jour utilisateur (nom, email)
PATCH	/v1/users/{id}/password	self ou admin	rotater mot de passe
PATCH	/v1/users/{id}/role	admin	changer rôle (admin/user/viewer)
DELETE	/v1/users/{id}	admin	retirer utilisateur
GET	/v1/orgs	tous	lister orgs
POST	/v1/orgs	admin	créer org
PATCH	/v1/orgs/{id}	admin	mettre à jour org
DELETE	/v1/orgs/{id}	admin	retirer org
GET	/v1/orgs/{id}/members	tous	lister membres
POST	/v1/orgs/{id}/members	admin	ajouter membre
PATCH	/v1/orgs/{id}/members/{user_id}	admin	changer rôle de membre
DELETE	/v1/orgs/{id}/members/{user_id}	admin	retirer membre

edge (l'agent connecté au tunnel)

Méthode	Chemin	Rôle	Description
POST	/v1/edges	edge:*	créer edge, émet clés access+secret
GET	/v1/edges	tous	lister edges
GET	/v1/edges/{id}	tous	obtenir détail d'edge
DELETE	/v1/edges/{id}	edge:*	supprimer edge
POST	/v1/edges/{id}/rotate-secret	edge:*	rotater la clé secrète
POST	/v1/edges/{id}/upgrade	edge:*	déclencher upgrade d'agent distant avec URL+sha256 explicites
POST	/v1/edges/{id}/upgrade-package	edge:*	upgrade de bundle en un clic (ADR-024)
GET	/v1/edges/{id}/processes	tous	liste de processus lecture seule (RPC à la demande)
GET	/v1/edges/{id}/plugins	tous	lister les plugins configurés + live de l'edge (avec santé)
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	activer/désactiver + tuner un plugin
GET	/v1/integrations/plugin-counts	tous	comptes globaux d'activation/désactivation de plugins (pour la tile homepage)

device (entité host, découplée de l'état du tunnel)

Méthode	Chemin	Rôle	Description
GET	/v1/devices	tous	lister devices host
GET	/v1/devices/{id}	tous	obtenir détail de device
PATCH	/v1/devices/{id}	device:*	mettre à jour nom d'affichage, tags
DELETE	/v1/devices/{id}	device:*	retirer device
PATCH	/v1/devices/{id}/roles	device:*	assigner rôles (db, web, cache...)
GET	/v1/devices/{id}/edges	tous	edges représentant actuellement ce device
GET	/v1/devices/{device_id}/shell	webshell	ouvrir un stream WebSSH (upgrade websocket)

topology (CMDB typé)

Méthode	Chemin	Rôle	Description
GET	/v1/topology/node-types	tous	lister schémas de node-type
POST	/v1/topology/node-types	topology:*	créer type de nœud
GET	/v1/topology/node-types/{name}	tous	obtenir un type de nœud
DELETE	/v1/topology/node-types/{name}	topology:*	retirer type de nœud
GET	/v1/topology/nodes	tous	lister nœuds (filtrer par type, tag)
POST	/v1/topology/nodes	topology:*	créer nœud
GET	/v1/topology/nodes/{id}	tous	obtenir nœud
PATCH	/v1/topology/nodes/{id}	topology:*	mettre à jour nœud
DELETE	/v1/topology/nodes/{id}	topology:*	retirer nœud
GET	/v1/topology/relation-types	tous	lister schémas de relation-type
POST	/v1/topology/relation-types	topology:*	créer type de relation
GET	/v1/topology/relation-types/{name}	tous	obtenir un type de relation
DELETE	/v1/topology/relation-types/{name}	topology:*	retirer type de relation
GET	/v1/topology/relations	tous	lister arêtes (relations)
POST	/v1/topology/relations	topology:*	créer relation
GET	/v1/topology/relations/{id}	tous	obtenir relation
PATCH	/v1/topology/relations/{id}	topology:*	mettre à jour relation
DELETE	/v1/topology/relations/{id}	topology:*	retirer relation

alert (règles, incidents, canaux)

Méthode	Chemin	Rôle	Description
GET	/v1/alert-rules	tous	lister règles
POST	/v1/alert-rules	alert:*	créer règle
GET	/v1/alert-rules/{id}	tous	obtenir règle
PUT	/v1/alert-rules/{id}	alert:*	remplacer règle
DELETE	/v1/alert-rules/{id}	alert:*	retirer règle
POST	/v1/alert-rules/{id}/enabled	alert:*	basculer le flag enabled
POST	/v1/alert-rules/preview	alert:*	dry-run une définition de règle contre les données courantes
GET	/v1/alerts/incidents	tous	lister incidents (filtres : statut, sévérité, scope)
GET	/v1/alerts/incidents/{id}	tous	obtenir incident
GET	/v1/alerts/incidents/{id}/events	tous	timeline d'événements
POST	/v1/alerts/incidents/{id}/ack	tous	acknowledger
POST	/v1/alerts/incidents/{id}/resolve	tous	marquer résolu
POST	/v1/alerts/incidents/{id}/silence	tous	silencer pour N heures
GET	/v1/alerts/incidents/{id}/investigation	tous	obtenir le rapport d'investigation généré par IA
POST	/v1/alerts/incidents/{id}/investigation	tous	déclencher ou ré-exécuter l'investigation
GET	/v1/alerts/runtime-info	tous	pace d'evaluator + stats du dernier cycle
GET	/v1/notification-channels	tous	lister canaux
POST	/v1/notification-channels	channel:*	créer canal
GET	/v1/notification-channels/{id}	tous	obtenir canal
PUT	/v1/notification-channels/{id}	channel:*	remplacer canal
DELETE	/v1/notification-channels/{id}	channel:*	retirer canal
POST	/v1/notification-channels/{id}/test	channel:*	envoyer une notification synthétique

Voir Schéma de règle d'alerte pour la forme JSON d'une règle.

aiops (chat, agents, modèles)

Méthode	Chemin	Rôle	Description
GET	/v1/agents	tous	lister personas d'agent
GET	/v1/agents/{name}	tous	obtenir détail de persona
DELETE	/v1/agents/{name}	agent:*	supprimer une persona built-in / disk (rare ; généralement seul custom est supprimable)
POST	/v1/agents/custom	agent:*	créer une persona user-défini
PATCH	/v1/agents/custom/{name}	agent:*	mettre à jour persona user
DELETE	/v1/agents/custom/{name}	agent:*	supprimer persona user
GET	/v1/chat/sessions	tous	lister sessions
POST	/v1/chat/sessions	tous	créer session
PATCH	/v1/chat/sessions/{id}	tous	renommer / taguer une session
DELETE	/v1/chat/sessions/{id}	tous	supprimer session
GET	/v1/chat/sessions/{id}/messages	tous	historique de messages
POST	/v1/chat/sessions/{id}/messages	tous	envoyer un message (non-streaming, renvoie la réponse finale)
POST	/v1/chat/sessions/{id}/messages/stream	tous	envoyer un message (stream SSE d'événements token + tool-call)
GET	/v1/aiops/models	tous	providers + modèles disponibles (gaté par les clés d'API configurées)
POST	/v1/aiops/query-translate	tous	composition PromQL / LogQL / TraceQL assistée par LLM
GET	/v1/aiops/mentions/search	tous	autocomplete pour les mentions @edge, @device, @dashboard
GET	/v1/usage/today	tous	utilisation de tokens pour le jour UTC courant

Voir Format de persona d'agent pour la forme du frontmatter markdown.

knowledge (RAG, vault, repos, uploads)

Méthode	Chemin	Rôle	Description
GET	/v1/knowledge/docs	tous	lister documents (arbre)
POST	/v1/knowledge/docs	knowledge:*	créer document
GET	/v1/knowledge/docs/{id}	tous	obtenir document
PATCH	/v1/knowledge/docs/{id}	knowledge:*	éditer corps de document
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	déplacer vers un autre chemin
DELETE	/v1/knowledge/docs/{id}	knowledge:*	retirer document
GET	/v1/knowledge/paths	tous	lister nœuds de chemin (pour l'arbre)
GET	/v1/knowledge/repos	tous	lister repos Git
POST	/v1/knowledge/repos	knowledge:*	enregistrer un repo
DELETE	/v1/knowledge/repos/{id}	knowledge:*	retirer repo
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	déclencher une re-sync
POST	/v1/knowledge/upload	knowledge:*	uploader .md / .txt / .pdf / .docx (parsé via docextract)
GET	/v1/knowledge/search	tous	requête RAG (renvoie chunks + scores)
POST	/v1/knowledge/vault/sync	knowledge:*	re-tirer le vault intégré depuis GitHub
GET	/v1/knowledge/ssh-identities	knowledge:*	lister clés SSH pour auth Git
POST	/v1/knowledge/ssh-identities	knowledge:*	enregistrer une clé SSH existante
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	générer un nouveau keypair (la clé privée ne quitte jamais le serveur)
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	éditer identité (nom, commentaire)
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	retirer identité

skill (introspection du sac d'outils)

Méthode	Chemin	Rôle	Description
GET	/v1/skills	tous	lister skills (scope manager + scope edge)
GET	/v1/skills/{key}	tous	obtenir détail de skill (schéma, description, scope, class)
POST	/v1/skills/{key}/execute	skill:*	exécution directe de skill (test / debugging)

Voir Manifeste de skill pour la forme skill.json sur disque.

logs / traces (proxies en lecture seule)

Méthode	Chemin	Rôle	Description
GET	/v1/logs/query_range	tous	LogQL query_range proxifié
GET	/v1/logs/labels	tous	label-names proxifiés
GET	/v1/logs/labels/{name}/values	tous	label-values proxifiés
GET	/v1/traces/search	tous	TraceQL /api/search proxifié
GET	/v1/traces/{trace_id}	tous	une trace par ID
GET	/v1/traces/tags/{tag}/values	tous	/api/search/tag/.../values proxifié

monitor (dashboards / panels)

Méthode	Chemin	Rôle	Description
GET	/v1/monitor/panels	tous	lister panels
POST	/v1/monitor/panels	monitor:*	créer panel
PATCH	/v1/monitor/panels/{id}	monitor:*	éditer panel
DELETE	/v1/monitor/panels/{id}	monitor:*	retirer panel
GET	/v1/observability/dashboards/{uid}	tous	JSON de dashboard Grafana prêt à rendre

metric (snapshot de métrique par edge)

Méthode	Chemin	Rôle	Description
GET	/v1/edges/{id}/metrics	tous	dernier snapshot de métrique host en ensemble fermé

prometheus (admin)

Méthode	Chemin	Rôle	Description
POST	/v1/prometheus/launch	admin	(re-)lancer le Prometheus embarqué
POST	/v1/prometheus/query_range	tous	query_range pour outils LLM (renvoie matrix normalisée)

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

Méthode	Chemin	Rôle	Description
GET	/v1/im/apps	tous	lister apps IM connectées
POST	/v1/im/apps	im:*	enregistrer app IM
GET	/v1/im/apps/{id}	tous	obtenir app
PUT	/v1/im/apps/{id}	im:*	mettre à jour app
DELETE	/v1/im/apps/{id}	im:*	retirer app
POST	/v1/im/apps/{id}/reveal	admin	révéler secrets masqués

marketplace (skill packs)

Méthode	Chemin	Rôle	Description
GET	/v1/marketplace/registries	tous	lister registries configurés
GET	/v1/marketplace/installed	tous	lister packs installés
POST	/v1/marketplace/install	marketplace:*	installer pack depuis un registry
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	désinstaller pack

setting (settings système : intégrations, défauts, secrets)

Méthode	Chemin	Rôle	Description
GET	/v1/system-settings	tous	lister settings visibles
PUT	/v1/system-settings/{category}/{key}	admin	upsert setting
DELETE	/v1/system-settings/{category}/{key}	admin	retirer setting
GET	/v1/system-settings/{category}/{key}/reveal	admin	révéler secret masqué

integration (tests de connectivité)

Méthode	Chemin	Rôle	Description
POST	/v1/integrations/grafana/sync	admin	sync dashboards + datasources
POST	/v1/integrations/grafana/test	admin	tester la connexion Grafana
POST	/v1/integrations/llm/invalidate	admin	invalider le client LLM caché (force re-lecture des clés API)
POST	/v1/integrations/loki/test	admin	tester la connexion Loki
POST	/v1/integrations/prom/test	admin	tester la connexion Prometheus
POST	/v1/integrations/tempo/test	admin	tester la connexion Tempo
POST	/v1/integrations/websearch/test	admin	tester le backend SearXNG / web-search

webshell (shell interactif sur le tunnel)

Méthode	Chemin	Rôle	Description
GET	/v1/devices/{device_id}/shell	webshell	ouvrir stream SSH upgradé en WebSocket
GET	/v1/webshell/sessions	tous	lister sessions actives
DELETE	/v1/webshell/sessions/{id}	webshell	tuer une session

audit (log admin)

Méthode	Chemin	Rôle	Description
GET	/v1/admin/audit-logs	admin	piste d'audit tenant-wide (HLD-010)

Pagination

Les endpoints de liste utilisent des curseurs opaques :

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

La réponse porte {"items":[...], "next_cursor":"...", "total":...}. next_cursor est vide à la dernière page.

Rate limits

Il n'y a pas de rate limits globaux dans le build open-source. Le gate de budget LLM (ONGRID_LLM_DAILY_TOKEN_LIMIT) borne le trafic de chat — chaque autre endpoint dépend de ce que vous mettez devant le manager (nginx, votre propre gateway).

Versioning

GET /v1/version renvoie {"manager_version":"vX.Y.Z"}. La SPA lit ceci et flag les edges dont la version d'agent dérive du manager. Utilisez-le pour l'outillage d'upgrade.

Voir aussi

• Variables d'environnement — ce qui contrôle le comportement de l'API.
• Schéma de règle d'alerte — corps de requête pour /v1/alert-rules.
• Manifeste de skill — corps de requête pour /v1/skills et install marketplace.
• Format de persona d'agent — corps de requête pour /v1/agents/custom.