Betriebsdashboard-API

Guida stellt eine kleine schreibgeschützte Betriebs-API bereit, um lange Crawls und Indexierungsläufe zu überwachen, ohne die Desktopoberfläche zu öffnen. Sie ist für Skripte, Agenten, leichte Dashboards und Monitoring-Clients im privaten Netzwerk gedacht.

Sie ist keine Fernsteuerungsoberfläche. Die Dashboard-API startet oder stoppt keine Worker, versucht keine Items erneut, löscht keine Queue-Einträge, verschiebt nichts in Fehlerwarteschlangen, führt keine Skripte aus, navigiert keine Tabs und ruft keine MCP-Werkzeuge auf.

Wenn ein Client im privaten Netzwerk explizite Steuerung braucht, verwenden Sie die Remote Ops API. Wenn er nur Zustand beobachten soll, verwenden Sie diese API.

Für deterministische Test-Harnesses mit token-geschützten Automatisierungsendpunkten verwenden Sie den Automatisierungsmodus. Für lokale KI-Werkzeuge mit Freigaben und Nachverfolgungsprotokoll verwenden Sie MCP.

Basis-URL

Standardmäßig lauscht der eingebettete Server auf Loopback:

http://127.0.0.1:9315

Wenn in Settings eine sichere private Bind-Adresse konfiguriert ist, bleibt Loopback aktiv und Guida stellt die schreibgeschützte Dashboard-API zusätzlich auf dieser Adresse bereit, zum Beispiel für NetBird- oder LAN-Monitoring:

http://100.68.25.200:9315

Statusantworten enthalten dashboardUrl, dashboardBindAddress, dashboardPort, applicationVersion und stabile Knotenidentität, damit ein Client anzeigen kann, welchen Guida-Knoten er überwacht.

Sicherheitsmodell

Die Dashboard-API ist bewusst enger gefasst als MCP.

Client	Erlaubt
Lokaler Loopback-Client	MCP plus Dashboard-Endpunkte
Remote-Client im privaten Netzwerk	Nur schreibgeschützte Dashboard-Endpunkte
Remote-`POST`, `PUT`, `DELETE` auf Dashboard-Pfade	Abgewiesen
Remote-MCP-Pfade	Abgewiesen
Remote-`/api/ops/*`	Nur wenn Remote Ops aktiviert ist
Öffentliche Wildcard-Bind-Adresse wie `0.0.0.0`	Durch Einstellungen abgewiesen

Remote-Dashboard-Clients sollten GET verwenden. HEAD ist ebenfalls schreibgeschützt. OPTIONS-Preflight wird nur akzeptiert, wenn die angefragte Methode schreibgeschützt ist.

Alle Dashboard-Lesungen setzen No-Cache-Header. Snapshot-Lesungen haben ein kurzes Timeout; langsame Lesevorgänge geben eine 503-Problemantwort zurück, statt Crawl-Arbeit unbegrenzt zu blockieren.

Endpunkte

Alle primären Endpunkte liegen unter /api/dashboard.

Endpunkt	Zweck
`GET /api/dashboard/status`	Kompakter Heartbeat für App, Arbeitsbereich, Workflow, aktive Ausführung, Worker und Runtime
`GET /api/dashboard/snapshot`	Kombinierter begrenzter Betriebssnapshot
`GET /api/dashboard/runs`	Aktuelle Workflow-Ausführungen
`GET /api/dashboard/runs/{runId}`	Detail für eine Ausführung
`GET /api/dashboard/runs/{runId}/counts`	Stage/State-Zählungen über die ganze Ausführung
`GET /api/dashboard/queues`	Queue-Zählungen und Gesamtsummen
`GET /api/dashboard/workers`	Worker-Pool-Zustand
`GET /api/dashboard/failures`	Aktuelle Task- und Ausführungsfehler
`GET /api/dashboard/attention`	Aktuelle Aufmerksamkeitspunkte
`GET /api/dashboard/reconcile/{runId}`	Fetch/Parse/Index-Handoff-Zusammenfassung
`GET /api/dashboard/events`	Server-Sent Events für Live-Invalidierung und Heartbeats

Antwortkonventionen

JSON-Eigenschaften verwenden camelCase. Viele Endpunkte liefern begrenzte Listen:

{
  "items": [],
  "totalCount": 0,
  "limit": 50,
  "truncated": false,
  "degraded": false,
  "errors": []
}

Wenn truncated true ist, enthält items nur die begrenzte Seite oder Stichprobe, während totalCount die volle bekannte Anzahl meldet. Für Aggregatfragen zählen die Aggregatfelder, nicht die Länge von items.

Wenn degraded true ist, konnte ein Teil des Snapshots nicht gesammelt werden. Die Antwort bleibt als Teilzustand nützlich; errors erklärt den Fehler.

Status

GET /api/dashboard/status ist der kompakte Heartbeat:

curl http://127.0.0.1:9315/api/dashboard/status

Wichtige Felder:

Feld	Bedeutung
`workspaceOpen`	Ob ein Arbeitsbereich geöffnet ist
`activeWorkflowName`	Aktive Workflow-Auswahl
`workersRunning`, `workersPaused`	Worker-Zustand
`runningTaskCount`	Laufende Skriptaufgaben
`activeRun`	Laufende oder zuletzt bekannte Workflow-Ausführung
`degraded`, `errors`	Teilfehler beim Lesen
`version`	Monotone Dashboard-Invalidierungsversion
`applicationVersion`	Semantische Guida-Version
`dashboardBindAddress`, `dashboardPort`, `dashboardUrl`	Von Guida angenommene Dashboard-Adresse
`nodeIdentity`, `nodeId`, `nodeName`, `nodeRole`, `machineName`	Knotenmetadaten für Multi-Node-Ansichten
`workerCountsByStatus`	Aggregierte Worker-Zustände

Snapshot

GET /api/dashboard/snapshot liefert einen kombinierten Betriebssnapshot für initiale Ladevorgänge und Resyncs.

curl "http://127.0.0.1:9315/api/dashboard/snapshot?forceReload=true"

Der Snapshot enthält Arbeitsbereichskontext, Queue-Zeilen, Worker-Pools, Task-Zählungen, Workflow-Ledger-Aggregate, aktuelle Ausführungen, aktuelle Fehler, Aufmerksamkeitspunkte, aktive Ausführung, Reconciliation und Knotenidentität.

forceReload=true umgeht den kurzlebigen Cache und liest direkt aus Repository- und Service-Zustand.

Reconciliation

GET /api/dashboard/reconcile/{runId} fasst Übergaben zwischen Fetch, Parse und Index für eine Ausführung zusammen. Das ist nützlich, wenn ein Crawl scheinbar stehen geblieben ist und Sie wissen müssen, ob Arbeit upstream verarbeitet, übersprungen, fehlgeschlagen, in Ausführung, reserviert oder downstream neu eingereiht wurde.

Die Reconciliation ist bewusst kompakt. Für detaillierte Wiederherstellung nutzen Sie die Workflow Ledger Console, und für ausführbare Queue-Arbeit die Queue Console.

SSE-Events

GET /api/dashboard/events sendet Live-Hinweise als Server-Sent Events. Diese Events sind Invalidierungs- und Heartbeat-Signale, keine dauerhafte Wahrheit. Ein Client sollte nach relevanten Events den fokussierten Zustand erneut über status, snapshot oder spezifische Endpunkte laden.

Grenzen

Die Betriebsdashboard-API ist nur lesend. Für lokale KI-Werkzeugsteuerung nutzen Sie MCP. Für Remote-Steuerung über einen gesicherten Kanal nutzen Sie Remote Ops. Für deterministische Test-Harnesses nutzen Sie den Automatisierungsmodus.