API du tableau de bord opérationnel

Guida expose une petite API opérationnelle en lecture seule pour superviser les crawls longs et les exécutions d’indexation sans ouvrir l’interface desktop. Elle vise les scripts, agents, tableaux de bord légers et clients de supervision sur réseau privé.

Ce n’est pas une surface de contrôle distant. L’API du tableau de bord ne démarre pas les processus, ne les arrête pas, ne réessaie pas des éléments, ne supprime pas d’entrées de file, n’envoie pas de travail vers la file des rejets, n’exécute pas de scripts, ne navigue pas dans les onglets et n’appelle pas d’outils MCP.

Utilisez l’API Remote Ops lorsqu’un client sur réseau privé a besoin d’un contrôle distant explicite. Utilisez cette API de tableau de bord lorsque le client doit seulement observer l’état.

Pour des harnais de test déterministes avec endpoints d’automatisation protégés par jeton, utilisez le mode d’automatisation. Pour les outils IA locaux avec autorisations et traçabilité, utilisez l’intégration MCP.

URL de base

Par défaut, le serveur intégré écoute sur l’interface de bouclage :

http://127.0.0.1:9315

Lorsqu’une adresse d’écoute privée sûre est configurée dans Settings, Guida garde l’interface de bouclage disponible et expose aussi l’API de tableau de bord en lecture seule sur cette adresse privée. C’est utile pour une supervision via NetBird ou LAN, par exemple :

http://100.68.25.200:9315

La charge utile de statut inclut dashboardUrl, dashboardBindAddress, dashboardPort, applicationVersion et des champs stables d’identité de nœud afin qu’un client puisse afficher l’adresse et le nœud Guida qu’il supervise.

Modèle de sécurité

L’API du tableau de bord est volontairement plus étroite que MCP.

Client	Autorisé
Client local sur boucle locale	MCP plus endpoints de tableau de bord
Client distant sur réseau privé	Endpoints de tableau de bord en lecture seule uniquement
POST, PUT, DELETE, etc. distants vers les chemins du tableau de bord	Rejetés
Chemins MCP distants sur réseau privé	Rejetés
/api/ops/* distant sur réseau privé	Disponible seulement si l’API Remote Ops est activée explicitement
Liaison wildcard publique comme 0.0.0.0	Rejetée par la validation des paramètres

Les clients distants du tableau de bord doivent utiliser des requêtes GET. HEAD est aussi traité comme lecture seule. Le preflight OPTIONS est accepté seulement si la méthode demandée est en lecture seule.

Les appels d’outils MCP utilisent POST sur la surface MCP locale. Remote Ops utilise POST /api/ops/rpc uniquement lorsque cette fonctionnalité est activée. Les clients du tableau de bord ne doivent pas utiliser POST ; cette API ne contient aucune mutation.

Les adresses d’écoute sûres incluent la boucle locale, les plages IPv4 privées RFC1918, la plage NetBird/CGNAT 100.64.0.0/10, l’IPv4 link-local, les adresses IPv6 locales uniques et les adresses IPv6 link-local. Les adresses wildcard et publiques retombent sur la boucle locale.

Toutes les lectures du tableau de bord définissent des en-têtes no-cache. Les lectures d’instantané sont protégées par un court délai ; une lecture lente renvoie une réponse problème 503 plutôt que de bloquer indéfiniment le travail de crawl.

Résumé des endpoints

Tous les endpoints principaux vivent sous /api/dashboard.

Endpoint	Usage
GET /api/dashboard/status	Pulsation compacte de l’application, de l’espace de travail, du flux, de l’exécution active, des processus et du runtime
GET /api/dashboard/snapshot	Instantané opérationnel combiné et borné
GET /api/dashboard/runs	Exécutions récentes de flux de travail
GET /api/dashboard/runs/{runId}	Détail d’une exécution
GET /api/dashboard/runs/{runId}/counts	Compteurs étape/état sur toute l’exécution
GET /api/dashboard/queues	Compteurs de files et totaux de files
GET /api/dashboard/workers	État des pools de processus
GET /api/dashboard/failures	Raisons récentes de tâches et exécutions en échec
GET /api/dashboard/attention	Éléments d’attention courants
GET /api/dashboard/reconcile/{runId}	Synthèse du passage fetch/parse/index pour une exécution
GET /api/dashboard/events	Flux Server-Sent Events pour invalidations et pulsations en direct

Conventions de réponse

Les propriétés JSON utilisent camel case.

Beaucoup d’endpoints renvoient des listes bornées. Une réponse de liste bornée utilise cette enveloppe :

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

Lorsque truncated vaut true, l’endpoint a renvoyé la première page ou un échantillon borné, mais totalCount indique toujours le total connu par le dépôt ou service. Pour les questions agrégées, utilisez les champs d’agrégat, pas la longueur de items.

Lorsque degraded vaut true, une partie de l’instantané n’a pas pu être collectée. La réponse reste un état partiel utile, et errors explique ce qui a échoué.

GET /api/dashboard/status

Renvoie une pulsation compacte pour l’instance Guida en cours d’exécution.

Utilisez cet endpoint pour contrôles de santé, titres de fenêtre, diagnostics entre pairs et cartes « Guida est-il vivant ? ».

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

Exemple de réponse :

{
  "generatedAt": "2026-05-24T18:30:20.082Z",
  "workspaceOpen": true,
  "workspaceName": "btbrowser-workspace",
  "workspacePath": "C:\\dev\\btbrowser-workspace",
  "activeWorkflowName": "careers-crawl",
  "workersRunning": true,
  "workersPaused": false,
  "runningTaskCount": 4,
  "unreadNotificationCount": 0,
  "activeRun": {
    "id": "92d987e072ab4649a5a7f1846446a420",
    "workflowName": "careers-crawl",
    "status": "running",
    "source": "manual",
    "startedAt": "2026-05-23T08:12:00Z",
    "finishedAt": null,
    "lastError": null
  },
  "degraded": false,
  "errors": [],
  "version": 9,
  "applicationVersion": "0.7.3-alpha.0",
  "applicationStartedAt": "2026-05-24T18:28:05.264Z",
  "dashboardBindAddress": "100.68.25.200",
  "dashboardPort": 9315,
  "dashboardUrl": "http://100.68.25.200:9315",
  "nodeIdentity": {
    "nodeId": "guida-b20ba90d102443c8a74f4c9903dce78d",
    "nodeName": "desktop-crawler",
    "nodeRole": "crawler",
    "machineName": "DESKTOP-QGUCB5J"
  },
  "nodeId": "guida-b20ba90d102443c8a74f4c9903dce78d",
  "nodeName": "desktop-crawler",
  "nodeRole": "crawler",
  "machineName": "DESKTOP-QGUCB5J",
  "workerCountsByStatus": {
    "running": 2,
    "idle": 1,
    "stopped": 4
  },
  "workerRunningCount": 2,
  "workerPausedCount": 0,
  "workerFailedCount": 0,
  "workerIdleCount": 1,
  "workerStoppedCount": 4,
  "workerStalledCount": 0
}

Champs importants :

Champ	Signification
workspaceOpen	Indique si un espace de travail est ouvert
activeWorkflowName	Sélection courante de flux dans l’espace de travail
workersRunning	Au moins un processus ou une tâche run-one est actif
workersPaused	Au moins un pool de processus est en pause
runningTaskCount	Nombre de tâches de script en cours
activeRun	Exécution de flux en cours si elle existe, sinon exécution la plus récente
degraded, errors	Indique si une partie de la lecture a échoué et pourquoi
version	Version monotone d’invalidation du tableau de bord
applicationVersion	Version sémantique de l’application Guida, par exemple 0.7.3-alpha.0 ; ne parsez pas de métadonnées de commit
applicationStartedAt	Horodatage de démarrage du processus
dashboardBindAddress, dashboardPort, dashboardUrl	Adresse que Guida pense servir
nodeIdentity, nodeId, nodeName, nodeRole, machineName	Métadonnées stables de nœud pour observateurs multi-nœuds
workerCountsByStatus, workerRunningCount, workerPausedCount, workerFailedCount, workerIdleCount, workerStoppedCount, workerStalledCount	Agrégats d’état des pools de processus

GET /api/dashboard/snapshot

Renvoie un instantané opérationnel combiné. Utilisez-le pour les chargements initiaux et les actions de resynchronisation forcée.

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

Paramètres de requête :

Paramètre	Type	Signification
forceReload	boolean	Si true, contourne le cache court et recharge depuis la vérité du dépôt/service

L’instantané inclut :

Champ	Signification
version, generatedAt	Identité et horodatage de l’instantané
workspaceName, workspacePath, activeWorkflowName	Contexte courant de l’espace de travail
queues	Lignes de files bornées
workerPools	Lignes de processus bornées
taskCountsByStatus	Compteurs de tâches de script groupés par statut
workflowLedger	Agrégats complets du registre
recentRuns	Liste bornée d’exécutions récentes
recentFailures	Liste bornée d’échecs de tâches/exécutions
attentionItems	Liste bornée d’éléments d’attention
activeRun	Résumé de l’exécution active ou la plus récente
activeRunReconciliation	Synthèse du passage fetch/parse/index pour l’exécution active
queuePendingCount, queueCheckedOutCount, queueCompletedCount, queueDeadLetterCount	Totaux complets des files
queueTotalsByState	Totaux de files groupés par état
totalQueueCount, queueLimit, queuesTruncated	Bornes de la liste des files
totalWorkerPoolCount, workerPoolLimit, workerPoolsTruncated	Bornes de la liste des pools
workerPoolCountsByStatus, workerPoolRunningCount, workerPoolPausedCount, workerPoolFailedCount, workerPoolIdleCount, workerPoolStoppedCount, workerPoolStalledCount	Agrégats complets d’état des processus
recentRunsTotalCount, recentRunsLimit, recentRunsTruncated	Bornes de la liste des exécutions récentes
recentFailuresTotalCount, recentFailuresLimit, recentFailuresTruncated	Bornes de la liste d’échecs
attentionItemsTotalCount, attentionItemsLimit, attentionItemsTruncated	Bornes de la liste d’attention
nodeIdentity, nodeId, nodeName, nodeRole, machineName	Métadonnées stables de nœud
degraded, errors	Métadonnées d’échec partiel

L’objet workflowLedger contient des données agrégées, pas un échantillon :

{
  "totalRuns": 12,
  "totalItems": 12242,
  "runCountsByStatus": {
    "running": 1,
    "completed": 10,
    "failed": 1
  },
  "itemCountsByState": {
    "queued": 923,
    "running": 21,
    "completed": 11189,
    "dead": 9
  },
  "itemCountsByStage": {
    "fetch": 285,
    "parse_index": 11672
  },
  "retryReadyCount": 0,
  "activeLeaseCount": 21,
  "expiredLeaseCount": 0,
  "attentionCount": 38
}

Les compteurs proviennent de requêtes d’agrégat du dépôt. Ils ne sont pas calculés depuis la première page d’éléments.

GET /api/dashboard/runs

Renvoie les exécutions récentes du flux actif.

curl "http://127.0.0.1:9315/api/dashboard/runs?take=10"

Paramètre	Type	Défaut	Max	Signification
take	integer	25	100	Nombre d’exécutions récentes à renvoyer

Forme de réponse :

{
  "items": [
    {
      "id": "92d987e072ab4649a5a7f1846446a420",
      "workflowName": "careers-crawl",
      "status": "running",
      "source": "manual",
      "startedAt": "2026-05-23T08:12:00Z",
      "finishedAt": null,
      "lastError": null
    }
  ],
  "totalCount": 12,
  "limit": 10,
  "truncated": true,
  "degraded": false,
  "errors": []
}

GET /api/dashboard/runs/{runId}

Renvoie le détail d’une exécution.

curl http://127.0.0.1:9315/api/dashboard/runs/92d987e072ab4649a5a7f1846446a420

Champ	Signification
run	Résumé d’exécution
stageStateCounts	Compteurs étape/état groupés sur toute l’exécution
reconciliation	Synthèse du passage fetch/parse/index
attentionItems	Échantillon borné d’attention limité à cette exécution

Si l’exécution n’existe pas, l’endpoint renvoie 404.

GET /api/dashboard/runs/{runId}/counts

Renvoie les compteurs groupés par étape et état sur toute l’exécution.

curl http://127.0.0.1:9315/api/dashboard/runs/92d987e072ab4649a5a7f1846446a420/counts

Exemple :

[
  {
    "stage": "fetch",
    "state": "queued",
    "count": 238,
    "problemCount": 0
  },
  {
    "stage": "parse_index",
    "state": "completed",
    "count": 11189,
    "problemCount": 0
  }
]

problemCount indique le nombre d’éléments de ce groupe qui sont en échec, prêts à réessayer, rejetés ou porteurs de métadonnées d’erreur. Cet endpoint est la bonne source pour les matrices étape/état. Il n’est pas limité par la taille de page des listes d’éléments.

Si l’exécution n’existe pas, l’endpoint renvoie 404.

GET /api/dashboard/queues

Renvoie des lignes de files bornées et les totaux complets.

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

Champ	Signification
items	Jusqu’à 100 lignes de files
totalCount	Nombre de files
limit	Limite de lignes de files, actuellement 100
truncated	Indique si certaines lignes ont été omises
totalPendingCount	Éléments en attente sur toutes les files
totalCheckedOutCount	Éléments pris en charge/en cours sur toutes les files
totalCompletedCount	Éléments terminés sur toutes les files
totalDeadLetterCount	Éléments dans la file des rejets sur toutes les files
totalsByState	Totaux complets groupés par état de file
degraded, errors	Métadonnées d’échec partiel

Chaque ligne de file ressemble à ceci :

{
  "name": "careers_fetch",
  "pendingCount": 471,
  "countsByState": {
    "Pending": 471,
    "CheckedOut": 21,
    "DeadLetter": 3
  },
  "checkedOutCount": 21,
  "completedCount": 0,
  "deadLetterCount": 3
}

GET /api/dashboard/workers

Renvoie des lignes bornées d’état des pools de processus et les compteurs agrégés.

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

Champs d’une ligne de processus :

Champ	Signification
queue	File traitée par ce pool
script	Chemin du script de processus
dequeueStrategy	Stratégie facultative de dépilage
concurrency	Concurrence configurée
activeWorkers	Boucles de processus en cours
processed	Éléments traités dans l’état courant du pool
failed	Éléments en échec dans l’état courant du pool
remaining	Éléments restants selon l’état du processus
paused	Indique si le pool est en pause
activeRunOneCount	Exécutions one-off actives
status	running, paused, stalled, failed, idle ou stopped
scope	global, workflow ou dynamic
checkedOutCount	Éléments pris en charge pour la file du pool

Les définitions de processus configurées apparaissent même lorsqu’elles sont arrêtées. Une définition arrêtée avec des éléments pris en charge dans la file est signalée comme stalled.

La réponse inclut aussi des agrégats :

Champ	Signification
countsByStatus	Compteurs de pools groupés par statut
runningCount, pausedCount, failedCount, idleCount, stoppedCount, stalledCount	Totaux complets par statut
activeWorkerCount	Somme des boucles de processus actives
activeRunOneCount	Somme des exécutions one-off actives

GET /api/dashboard/failures

Renvoie les tâches de script récemment en échec et les exécutions de flux échouées.

curl "http://127.0.0.1:9315/api/dashboard/failures?take=5"

Paramètre	Type	Défaut	Max	Signification
take	integer	25	100	Nombre de lignes d’échec à renvoyer

Champs d’une ligne d’échec :

Champ	Signification
taskId	ID de tâche de script ou ID d’exécution
name	Nom de tâche ou libellé d’exécution
origin	Origine de tâche, comme Worker, ou WorkflowLedger pour les exécutions échouées
status	Statut d’échec
startTime, endTime	Horodatages de tâche/exécution
error	Message d’échec
queueName, queueItemKey, workerIndex	Contexte de processus si disponible
mcpToolName, triggerEvent	Contexte MCP/déclencheur si disponible
kind	task ou workflow_run
workflowName, runId	Contexte de flux si disponible

GET /api/dashboard/attention

Renvoie les éléments d’attention pour le flux actif, ou pour une exécution sélectionnée lorsque runId est fourni.

curl "http://127.0.0.1:9315/api/dashboard/attention?take=20"
curl "http://127.0.0.1:9315/api/dashboard/attention?runId=92d987e072ab4649a5a7f1846446a420&take=20"

Paramètre	Type	Défaut	Max	Signification
runId	string	aucun	n/a	Limite l’attention à une exécution
take	integer	50	200	Nombre de lignes d’attention à renvoyer

Champs d’une ligne d’attention :

Champ	Signification
kind	expired_lease, dead_item, failed_item, retry_ready ou failed_run
severity	critical, error ou warning
workflowName, runId	Contexte de flux/exécution
itemId, itemKey	Identité de l’élément lorsque l’attention porte sur un élément
stage, state	Emplacement de l’élément de flux
message	Explication courte pour l’opérateur
timestamp	Horodatage pertinent d’événement ou de mise à jour
lastError	Dernière erreur enregistrée si disponible

GET /api/dashboard/reconcile/{runId}

Renvoie une réconciliation compacte du pipeline pour une exécution de flux.

curl http://127.0.0.1:9315/api/dashboard/reconcile/92d987e072ab4649a5a7f1846446a420

Exemple de réponse :

{
  "runId": "92d987e072ab4649a5a7f1846446a420",
  "workflowName": "careers-crawl",
  "totalItems": 12235,
  "stageStateCounts": [
    {
      "stage": "parse_index",
      "state": "completed",
      "count": 11189,
      "problemCount": 0
    }
  ],
  "fetchProcessedCount": 0,
  "fetchSkippedCount": 17,
  "fetchDeadCount": 9,
  "fetchRetryReadyCount": 0,
  "fetchRunningCount": 21,
  "fetchLeasedCount": 21,
  "parseIndexQueuedCount": 483,
  "parseIndexCompletedCount": 11189,
  "parseIndexReceivedCount": 11672,
  "fetchToParseMissingCount": 0,
  "parseIndexBacklogCount": 483,
  "handoffAttentionCount": 0,
  "handoffStatus": "backlog"
}

Utilisez cet endpoint pour répondre à des questions de passage :

• Combien d’éléments fetch sont encore en file, en cours, pris en charge, ignorés, rejetés ou prêts à réessayer ?
• Combien d’éléments parse/index sont en file ?
• Combien d’éléments parse/index sont terminés ?
• Combien d’éléments parse/index ont été reçus depuis fetch ?
• Existe-t-il un écart fetch-to-parse ou un backlog parse/index ?
• Le comptage complet étape/état correspond-il à la forme attendue du pipeline ?

Si l’exécution n’existe pas, l’endpoint renvoie 404.

GET /api/dashboard/events

Ouvre un flux Server-Sent Events pour les mises à jour en direct du tableau de bord.

curl -N http://127.0.0.1:9315/api/dashboard/events

Le flux envoie seulement des indices compacts. Il n’envoie pas d’instantanés complets. Un client doit traiter les événements comme « quelque chose a changé » puis appeler l’endpoint ciblé dont il a besoin, généralement /api/dashboard/status, /api/dashboard/snapshot?forceReload=true ou un endpoint d’exécution sélectionnée.

Événement de connexion initial :

event: status
data: {"occurredAt":"2026-05-24T18:36:00.0398288+00:00","version":9,"status":"connected","workspaceOpen":true,"workspaceName":"btbrowser-workspace","activeWorkflowName":"careers-crawl","workersRunning":true,"workersPaused":false,"runningTaskCount":4,"unreadNotificationCount":0,"degraded":false,"errors":[],"applicationVersion":"0.7.3-alpha.0","applicationStartedAt":"2026-05-24T18:28:05.2641123+00:00","dashboardBindAddress":"100.68.25.200","dashboardPort":9315,"dashboardUrl":"http://100.68.25.200:9315","nodeIdentity":{"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"},"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"}

Événement de pulsation :

event: status
data: {"occurredAt":"2026-05-24T18:36:47.6112429+00:00","version":9,"status":"heartbeat","workspaceOpen":true,"workersRunning":true,"degraded":false,"errors":[],"applicationVersion":"0.7.3-alpha.0","nodeIdentity":{"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"},"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","machineName":"DESKTOP-QGUCB5J"}

Événement d’invalidation :

event: invalidation
data: {"occurredAt":"2026-05-24T18:36:12.1000000+00:00","version":10,"reason":"operational_event"}

Types d’événements :

Événement	Signification
status avec status: "connected"	Flux ouvert avec succès
status avec status: "heartbeat"	Flux encore actif ; l’intervalle par défaut est de 15 secondes
invalidation	État de l’espace de travail, des files, processus, tâches, registre ou notifications modifié

Les événements de statut incluent les mêmes champs compacts d’application, espace de travail et identité de nœud que /api/dashboard/status. Ils restent des instantanés de statut, pas des instantanés complets du tableau de bord.

Le canal SSE est borné. Si beaucoup d’invalidations arrivent rapidement, Guida peut abandonner les anciens indices d’invalidation. C’est sûr, car les événements sont des indices et les dépôts restent la source de vérité.

Codes de statut

Statut	Signification
200	Réponse JSON ou flux SSE réussi
403	Un client distant a tenté un chemin hors tableau de bord ou une méthode non lecture
404	L’exécution sélectionnée n’existe pas, ou une route inexistante comme /dashboard a été demandée localement
499	Le client s’est déconnecté avant la fin de la lecture
503	La lecture du tableau de bord a expiré
500	La lecture du tableau de bord a échoué de façon inattendue

Conseils client

• Utilisez /api/dashboard/status pour les contrôles de présence peu coûteux.
• Utilisez /api/dashboard/snapshot?forceReload=true pour les chargements initiaux et resynchronisations explicites.
• Utilisez /api/dashboard/events pour savoir quand recharger l’état ciblé.
• Utilisez /api/dashboard/runs/{runId}/counts pour les matrices étape/état.
• Utilisez /api/dashboard/reconcile/{runId} pour les questions de passage fetch-to-parse/index.
• Utilisez applicationVersion comme version sémantique de l’application et nodeId comme identité stable du nœud Guida.
• Traitez les listes bornées comme des échantillons ou pages ; utilisez totalCount, les agrégats et truncated pour la vue complète.
• Ne sondez pas agressivement lorsqu’une connexion SSE est ouverte. Laissez les événements d’invalidation déclencher des rechargements ciblés.
• Ne supposez pas que les charges utiles d’événements sont un état durable. Rechargez depuis les endpoints JSON.

Étapes suivantes

• Intégration MCP — accès local aux outils MCP, autorisations et journalisation de traçabilité
• API Remote Ops — contrôle distant sur canal de confiance via JSON-RPC
• Registre de traçabilité des flux de travail — exécutions, éléments, compteurs étape/état et réconciliation durables
• Processus de travail des files d’attente — pools appuyés par des files et traitement par lot
• Files d’attente et révision — inspection des files et tri opérateur