REST-API-Referenz

Der Manager stellt eine einzige REST-API unter /api bereit. Die SPA in web/ ruft sie auf; Sie können sie direkt mit einem beliebigen HTTP-Client aufrufen. Es gibt kein GraphQL, kein gRPC für Anwendungsverkehr (gRPC wird nur für den geminio-Tunnel verwendet, intern im Manager).

Diese Seite ist ein Routen-Katalog, keine handgeschriebene Swagger-Spezifikation. Source of truth: cmd/ongrid/main.go (die chi.Router-Mounts) und internal/manager/server/*/http.go (die per-BC-Handler). Klicken Sie sich zum Handler durch für die genauen Request-/Response-Struct-Felder.

Konventionen

• Basispfad: jede Route hat das Präfix /api. Also wird GET /v1/edges unter https://<manager>/api/v1/edges erreicht.
• Versionierung: alle Routen liegen unter /v1/. Es gibt kein /v2/. Rückwärtsinkompatible Änderungen werden hinter Feature-Flags oder neuen Routen ausgeliefert.
• Auth: Bearer-JWT in Authorization: Bearer .... Öffentliche Routen (Login, Refresh, Register, IM-Webhooks, Prometheus' auth_request-Probe) überspringen die Middleware. Aufgelistet in der Tabelle „Öffentlich" unten.
• Rollen: admin, user, viewer. Schreibrouten erfordern admin (oder die entsprechende Casbin-Aktion wie edge:* / write); Leserouten akzeptieren jede authentifizierte Rolle. viewer darf chatten, aber der Toolbag des Agenten wird auf ClassSafe gefiltert. Siehe ADR-022 Drei-Rollen-RBAC.
• Fehler: JSON {"error":"code","message":"human text"}. Codes sind stabile Enums (not_found, invalid_argument, unauthorized, forbidden, conflict).
• Content-Type: jeder Request und jede Response ist application/json, sofern nicht explizit anders vermerkt (gestreamter Chat ist SSE, Log-/Trace-Ingest ist OTLP-Protobuf oder Loki-JSON).

Öffentliche Routen (keine Auth)

Methode	Pfad	Zweck
GET	/healthz	Liveness-Probe
GET	/readyz	Readiness-Probe
GET	/internal/auth/dataplane-verify	nginx-auth_request-Probe für Log-/Trace-Ingest
POST	/api/v1/auth/login	E-Mail+Passwort gegen JWT eintauschen
POST	/api/v1/auth/refresh	Refresh-Token gegen frisches Access-Token eintauschen
POST	/api/v1/auth/register	Selbstregistrierung (per Config gesteuert)
GET	/api/v1/prometheus/auth	nginx-auth_request-Probe für das Grafana-Embed
POST	/api/v1/im/feishu/events	eingehender Feishu/Lark-Callback; Webhook-Signatur ist die Auth

Authentifizierte Routen

iam (Benutzer, Orgs, Sessions)

Methode	Pfad	Rolle	Quelle
GET	/v1/version	beliebig	cmd/ongrid/main.go (inline)
GET	/v1/me	beliebig	internal/iam/server/http.go
GET	/v1/self	beliebig	internal/iam/server/http.go
GET	/v1/users	beliebig	Benutzer auflisten
POST	/v1/users	admin	Benutzer erstellen
PATCH	/v1/users/{id}	admin	Benutzer aktualisieren (Name, E-Mail)
PATCH	/v1/users/{id}/password	self oder admin	Passwort rotieren
PATCH	/v1/users/{id}/role	admin	Rolle ändern (admin/user/viewer)
DELETE	/v1/users/{id}	admin	Benutzer entfernen
GET	/v1/orgs	beliebig	Orgs auflisten
POST	/v1/orgs	admin	Org erstellen
PATCH	/v1/orgs/{id}	admin	Org aktualisieren
DELETE	/v1/orgs/{id}	admin	Org entfernen
GET	/v1/orgs/{id}/members	beliebig	Mitglieder auflisten
POST	/v1/orgs/{id}/members	admin	Mitglied hinzufügen
PATCH	/v1/orgs/{id}/members/{user_id}	admin	Mitgliederrolle ändern
DELETE	/v1/orgs/{id}/members/{user_id}	admin	Mitglied entfernen

edge (der tunnelverbundene Agent)

Methode	Pfad	Rolle	Beschreibung
POST	/v1/edges	edge:*	edge erstellen, gibt Access- und Secret-Key aus
GET	/v1/edges	beliebig	edges auflisten
GET	/v1/edges/{id}	beliebig	edge-Detail abrufen
DELETE	/v1/edges/{id}	edge:*	edge löschen
POST	/v1/edges/{id}/rotate-secret	edge:*	Secret-Key rotieren
POST	/v1/edges/{id}/upgrade	edge:*	Remote-Agent-Upgrade mit expliziter URL+sha256 auslösen
POST	/v1/edges/{id}/upgrade-package	edge:*	Ein-Klick-Bundle-Upgrade (ADR-024)
GET	/v1/edges/{id}/processes	beliebig	schreibgeschützte Prozessliste (on-demand RPC)
GET	/v1/edges/{id}/plugins	beliebig	konfigurierte + live Plugins der edge auflisten (mit Health)
PUT	/v1/edges/{id}/plugins/{name}	edge:plugin	Plugin aktivieren/deaktivieren + tunen
GET	/v1/integrations/plugin-counts	beliebig	globale Plugin-Aktivierungs-/Deaktivierungs-Zählungen (für Homepage-Kachel)

device (Host-Entität, entkoppelt vom Tunnel-Zustand)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/devices	beliebig	Host-Geräte auflisten
GET	/v1/devices/{id}	beliebig	Geräte-Detail abrufen
PATCH	/v1/devices/{id}	device:*	Anzeigename, Tags aktualisieren
DELETE	/v1/devices/{id}	device:*	Gerät entfernen
PATCH	/v1/devices/{id}/roles	device:*	Rollen zuweisen (db, web, cache...)
GET	/v1/devices/{id}/edges	beliebig	edges, die dieses Gerät derzeit repräsentieren
GET	/v1/devices/{device_id}/shell	webshell	einen WebSSH-Stream öffnen (Websocket-Upgrade)

topology (typisierte CMDB)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/topology/node-types	beliebig	Node-Type-Schemas auflisten
POST	/v1/topology/node-types	topology:*	Node-Type erstellen
GET	/v1/topology/node-types/{name}	beliebig	einen Node-Type abrufen
DELETE	/v1/topology/node-types/{name}	topology:*	Node-Type entfernen
GET	/v1/topology/nodes	beliebig	Knoten auflisten (filterbar nach Typ, Tag)
POST	/v1/topology/nodes	topology:*	Knoten erstellen
GET	/v1/topology/nodes/{id}	beliebig	Knoten abrufen
PATCH	/v1/topology/nodes/{id}	topology:*	Knoten aktualisieren
DELETE	/v1/topology/nodes/{id}	topology:*	Knoten entfernen
GET	/v1/topology/relation-types	beliebig	Relation-Type-Schemas auflisten
POST	/v1/topology/relation-types	topology:*	Relation-Type erstellen
GET	/v1/topology/relation-types/{name}	beliebig	einen Relation-Type abrufen
DELETE	/v1/topology/relation-types/{name}	topology:*	Relation-Type entfernen
GET	/v1/topology/relations	beliebig	Kanten (Relationen) auflisten
POST	/v1/topology/relations	topology:*	Relation erstellen
GET	/v1/topology/relations/{id}	beliebig	Relation abrufen
PATCH	/v1/topology/relations/{id}	topology:*	Relation aktualisieren
DELETE	/v1/topology/relations/{id}	topology:*	Relation entfernen

alert (Regeln, Incidents, Kanäle)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/alert-rules	beliebig	Regeln auflisten
POST	/v1/alert-rules	alert:*	Regel erstellen
GET	/v1/alert-rules/{id}	beliebig	Regel abrufen
PUT	/v1/alert-rules/{id}	alert:*	Regel ersetzen
DELETE	/v1/alert-rules/{id}	alert:*	Regel entfernen
POST	/v1/alert-rules/{id}/enabled	alert:*	enabled-Flag umschalten
POST	/v1/alert-rules/preview	alert:*	Dry-Run einer Regeldefinition gegen aktuelle Daten
GET	/v1/alerts/incidents	beliebig	Incidents auflisten (Filter: status, severity, scope)
GET	/v1/alerts/incidents/{id}	beliebig	Incident abrufen
GET	/v1/alerts/incidents/{id}/events	beliebig	Event-Timeline
POST	/v1/alerts/incidents/{id}/ack	beliebig	bestätigen
POST	/v1/alerts/incidents/{id}/resolve	beliebig	als aufgelöst markieren
POST	/v1/alerts/incidents/{id}/silence	beliebig	für N Stunden stummschalten
GET	/v1/alerts/incidents/{id}/investigation	beliebig	KI-generierten Investigation-Bericht abrufen
POST	/v1/alerts/incidents/{id}/investigation	beliebig	Investigation auslösen oder erneut ausführen
GET	/v1/alerts/runtime-info	beliebig	Evaluator-Takt + Stats des letzten Zyklus
GET	/v1/notification-channels	beliebig	Kanäle auflisten
POST	/v1/notification-channels	channel:*	Kanal erstellen
GET	/v1/notification-channels/{id}	beliebig	Kanal abrufen
PUT	/v1/notification-channels/{id}	channel:*	Kanal ersetzen
DELETE	/v1/notification-channels/{id}	channel:*	Kanal entfernen
POST	/v1/notification-channels/{id}/test	channel:*	synthetische Benachrichtigung senden

Siehe Alarmregel-Schema für die JSON-Form einer Regel.

aiops (Chat, Agenten, Modelle)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/agents	beliebig	Agent-Personas auflisten
GET	/v1/agents/{name}	beliebig	Persona-Detail abrufen
DELETE	/v1/agents/{name}	agent:*	eine eingebaute / Disk-Persona löschen (selten; meist nur custom löschbar)
POST	/v1/agents/custom	agent:*	benutzerdefinierte Persona erstellen
PATCH	/v1/agents/custom/{name}	agent:*	Benutzer-Persona aktualisieren
DELETE	/v1/agents/custom/{name}	agent:*	Benutzer-Persona löschen
GET	/v1/chat/sessions	beliebig	Sessions auflisten
POST	/v1/chat/sessions	beliebig	Session erstellen
PATCH	/v1/chat/sessions/{id}	beliebig	Session umbenennen / taggen
DELETE	/v1/chat/sessions/{id}	beliebig	Session löschen
GET	/v1/chat/sessions/{id}/messages	beliebig	Nachrichtenverlauf
POST	/v1/chat/sessions/{id}/messages	beliebig	Nachricht senden (nicht-streamend, gibt finale Antwort zurück)
POST	/v1/chat/sessions/{id}/messages/stream	beliebig	Nachricht senden (SSE-Stream von Token- + Tool-Call-Events)
GET	/v1/aiops/models	beliebig	verfügbare Provider + Modelle (gesteuert durch konfigurierte API-Keys)
POST	/v1/aiops/query-translate	beliebig	LLM-gestützte PromQL- / LogQL- / TraceQL-Komposition
GET	/v1/aiops/mentions/search	beliebig	Autovervollständigung für @edge-, @device-, @dashboard-Mentions
GET	/v1/usage/today	beliebig	Token-Nutzung für den aktuellen UTC-Tag

Siehe Agent-Persona-Format für die Markdown-Frontmatter-Form.

knowledge (RAG, Vault, Repos, Uploads)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/knowledge/docs	beliebig	Dokumente auflisten (Baum)
POST	/v1/knowledge/docs	knowledge:*	Dokument erstellen
GET	/v1/knowledge/docs/{id}	beliebig	Dokument abrufen
PATCH	/v1/knowledge/docs/{id}	knowledge:*	Dokumentkörper bearbeiten
PATCH	/v1/knowledge/docs/{id}/move	knowledge:*	an einen anderen Pfad verschieben
DELETE	/v1/knowledge/docs/{id}	knowledge:*	Dokument entfernen
GET	/v1/knowledge/paths	beliebig	Pfadknoten auflisten (für den Baum)
GET	/v1/knowledge/repos	beliebig	Git-Repos auflisten
POST	/v1/knowledge/repos	knowledge:*	Repo registrieren
DELETE	/v1/knowledge/repos/{id}	knowledge:*	Repo entfernen
POST	/v1/knowledge/repos/{id}/sync	knowledge:*	Re-Sync auslösen
POST	/v1/knowledge/upload	knowledge:*	.md / .txt / .pdf / .docx hochladen (geparst via docextract)
GET	/v1/knowledge/search	beliebig	RAG-Abfrage (gibt Chunks + Scores zurück)
POST	/v1/knowledge/vault/sync	knowledge:*	eingebauten Vault von GitHub erneut ziehen
GET	/v1/knowledge/ssh-identities	knowledge:*	SSH-Keys für Git-Auth auflisten
POST	/v1/knowledge/ssh-identities	knowledge:*	bestehenden SSH-Key registrieren
POST	/v1/knowledge/ssh-identities/generate	knowledge:*	neues Keypair generieren (Private Key verlässt nie den Server)
PATCH	/v1/knowledge/ssh-identities/{id}	knowledge:*	Identität bearbeiten (Name, Kommentar)
DELETE	/v1/knowledge/ssh-identities/{id}	knowledge:*	Identität entfernen

skill (Toolbag-Introspection)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/skills	beliebig	Skills auflisten (manager-scope + edge-scope)
GET	/v1/skills/{key}	beliebig	Skill-Detail abrufen (Schema, Beschreibung, Scope, Klasse)
POST	/v1/skills/{key}/execute	skill:*	direkte Skill-Ausführung (Test / Debugging)

Siehe Skill-Manifest für die On-Disk-skill.json-Form.

logs / traces (schreibgeschützte Proxies)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/logs/query_range	beliebig	gepproxytes LogQL query_range
GET	/v1/logs/labels	beliebig	gepproxyte Label-Namen
GET	/v1/logs/labels/{name}/values	beliebig	gepproxyte Label-Werte
GET	/v1/traces/search	beliebig	gepproxytes TraceQL /api/search
GET	/v1/traces/{trace_id}	beliebig	ein Trace nach ID
GET	/v1/traces/tags/{tag}/values	beliebig	gepproxytes /api/search/tag/.../values

monitor (Dashboards / Panels)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/monitor/panels	beliebig	Panels auflisten
POST	/v1/monitor/panels	monitor:*	Panel erstellen
PATCH	/v1/monitor/panels/{id}	monitor:*	Panel bearbeiten
DELETE	/v1/monitor/panels/{id}	monitor:*	Panel entfernen
GET	/v1/observability/dashboards/{uid}	beliebig	render-bereites Grafana-Dashboard-JSON

metric (pro-Edge-Metrik-Snapshot)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/edges/{id}/metrics	beliebig	letzter Closed-Set-Host-Metrik-Snapshot

prometheus (admin)

Methode	Pfad	Rolle	Beschreibung
POST	/v1/prometheus/launch	admin	das eingebettete Prometheus (neu) starten
POST	/v1/prometheus/query_range	beliebig	LLM-tool-orientiertes query_range (gibt normalisierte Matrix zurück)

imbridge (Chat-Oberflächen — Slack / Telegram / Lark / DingTalk / WeCom)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/im/apps	beliebig	verbundene IM-Apps auflisten
POST	/v1/im/apps	im:*	IM-App registrieren
GET	/v1/im/apps/{id}	beliebig	App abrufen
PUT	/v1/im/apps/{id}	im:*	App aktualisieren
DELETE	/v1/im/apps/{id}	im:*	App entfernen
POST	/v1/im/apps/{id}/reveal	admin	maskierte Secrets aufdecken

marketplace (Skill-Packs)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/marketplace/registries	beliebig	konfigurierte Registries auflisten
GET	/v1/marketplace/installed	beliebig	installierte Packs auflisten
POST	/v1/marketplace/install	marketplace:*	Pack aus einer Registry installieren
DELETE	/v1/marketplace/installed/{pack_id}	marketplace:*	Pack deinstallieren

setting (Systemeinstellungen: Integrationen, Defaults, Secrets)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/system-settings	beliebig	sichtbare Einstellungen auflisten
PUT	/v1/system-settings/{category}/{key}	admin	Einstellung upserten
DELETE	/v1/system-settings/{category}/{key}	admin	Einstellung entfernen
GET	/v1/system-settings/{category}/{key}/reveal	admin	maskiertes Secret aufdecken

integration (Konnektivitätstests)

Methode	Pfad	Rolle	Beschreibung
POST	/v1/integrations/grafana/sync	admin	Dashboards + Datasources synchronisieren
POST	/v1/integrations/grafana/test	admin	Grafana-Verbindung testen
POST	/v1/integrations/llm/invalidate	admin	gecachten LLM-Client invalidieren (erzwingt Neu-Lesen der API-Keys)
POST	/v1/integrations/loki/test	admin	Loki-Verbindung testen
POST	/v1/integrations/prom/test	admin	Prometheus-Verbindung testen
POST	/v1/integrations/tempo/test	admin	Tempo-Verbindung testen
POST	/v1/integrations/websearch/test	admin	SearXNG / Web-Search-Backend testen

webshell (interaktive Shell über den Tunnel)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/devices/{device_id}/shell	webshell	WebSocket-upgegradeten SSH-Stream öffnen
GET	/v1/webshell/sessions	beliebig	aktive Sessions auflisten
DELETE	/v1/webshell/sessions/{id}	webshell	eine Session beenden

audit (Admin-Log)

Methode	Pfad	Rolle	Beschreibung
GET	/v1/admin/audit-logs	admin	mandantenweite Audit-Spur (HLD-010)

Pagination

List-Endpunkte verwenden opake Cursor:

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

Die Antwort trägt {"items":[...], "next_cursor":"...", "total":...}. next_cursor ist auf der letzten Seite leer.

Rate Limits

Im Open-Source-Build gibt es keine globalen Rate Limits. Das LLM-Budget-Gate (ONGRID_LLM_DAILY_TOKEN_LIMIT) begrenzt den Chat-Traffic — jeder andere Endpunkt hängt von dem ab, was Sie vor den Manager stellen (nginx, Ihr eigenes Gateway).

Versionierung

GET /v1/version gibt {"manager_version":"vX.Y.Z"} zurück. Die SPA liest dies und markiert Edges, deren Agent-Version vom Manager abdriftet. Verwenden Sie es für Upgrade-Tooling.

Siehe auch

• Umgebungsvariablen — was das Verhalten der API steuert.
• Alarmregel-Schema — Request-Body für /v1/alert-rules.
• Skill-Manifest — Request-Body für /v1/skills und Marketplace-Install.
• Agent-Persona-Format — Request-Body für /v1/agents/custom.