Ir al contenido

API del panel operativo

Guida expone una pequeña API operativa en sola lectura para supervisar rastreos e indexaciones largas sin abrir la interfaz de escritorio. La API está pensada para scripts, agentes, paneles ligeros y clientes de supervisión en redes privadas.

No es una superficie de control remoto. La API del panel no inicia procesos de trabajo, no los detiene, no reintenta elementos, no elimina entradas de cola, no mueve trabajo a la cola de rechazos, no ejecuta scripts, no navega por pestanas y no llama a herramientas MCP.

Use la API de Remote Ops cuando un cliente de red privada necesite control remoto explícito. Use esta API del panel cuando el cliente solo necesite observar el estado.

Para bancos de pruebas deterministas con endpoints de automatización protegidos por token, use Modo de automatización. Para herramientas locales de IA con autorizaciones y registro de trazabilidad, use Integración MCP.

De forma predeterminada, el servidor integrado escucha en loopback:

http://127.0.0.1:9315

Cuando se configura una dirección privada segura en Settings, Guida mantiene disponible loopback y también expone la API del panel operativo en sola lectura en esa dirección privada. Esto resulta útil para supervisión por NetBird o LAN, por ejemplo:

http://100.68.25.200:9315

La carga de estado incluye dashboardUrl, dashboardBindAddress, dashboardPort, applicationVersion y campos estables de identidad del nodo para que un cliente pueda mostrar la dirección y el nodo de Guida que está supervisando.

La API del panel es deliberadamente más estrecha que MCP.

ClientePermitido
Cliente local por loopbackMCP y endpoints del panel
Cliente remoto de red privadaSolo endpoints del panel en sola lectura
POST, PUT, DELETE, etc. remotos de red privada contra rutas del panelRechazados
Rutas MCP remotas de red privadaRechazadas
/api/ops/* remoto de red privadaDisponible solo cuando la API de Remote Ops está habilitada explícitamente
Enlace comodín público como 0.0.0.0Rechazado por la validación de ajustes

Los clientes remotos del panel deben usar solicitudes GET. HEAD también se trata como sola lectura. El preflight OPTIONS se acepta solo cuando el método solicitado es de sola lectura.

Las llamadas a herramientas MCP usan POST en la superficie MCP local. Remote Ops usa POST /api/ops/rpc solo cuando esa función está habilitada. Los clientes del panel no deben usar POST; esta API no tiene mutaciones de panel.

Las direcciones de enlace seguras incluyen loopback, rangos IPv4 privados RFC1918, rangos de estilo NetBird/CGNAT 100.64.0.0/10, IPv4 link-local, direcciones locales únicas IPv6 y direcciones link-local IPv6. Las direcciones comodín y públicas vuelven a loopback.

Todas las lecturas del panel establecen cabeceras sin caché. Las lecturas de instantánea están protegidas por un tiempo de espera breve; una lectura lenta devuelve una respuesta de problema 503 en lugar de bloquear indefinidamente el trabajo de rastreo.

Todos los endpoints principales viven bajo /api/dashboard.

EndpointProposito
GET /api/dashboard/statusLatido compacto de aplicación, espacio de trabajo, flujo de trabajo, ejecución activa, procesos de trabajo y runtime
GET /api/dashboard/snapshotInstantanea operativa combinada y acotada
GET /api/dashboard/runsEjecuciones recientes de flujos de trabajo
GET /api/dashboard/runs/{runId}Detalle de una ejecución de flujo de trabajo
GET /api/dashboard/runs/{runId}/countsConteos completos de fase/estado para la ejecución
GET /api/dashboard/queuesConteos de colas y totales de cola
GET /api/dashboard/workersEstado de grupos de procesos de trabajo
GET /api/dashboard/failuresMotivos recientes de tareas y ejecuciones fallidas
GET /api/dashboard/attentionElementos actuales que requieren atención
GET /api/dashboard/reconcile/{runId}Resumen de traspaso entre captura, análisis e indexación para una ejecución
GET /api/dashboard/eventsFlujo Server-Sent Events para invalidaciones y latidos en vivo

Las propiedades JSON usan camel case.

Muchos endpoints devuelven listas acotadas. Una respuesta de lista acotada usa este contenedor:

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

Cuando truncated es true, el endpoint devolvió la primera página o muestra acotada, pero totalCount sigue indicando el conteo completo conocido por el repositorio o servicio. Para preguntas agregadas, use los campos agregados, no la longitud de items.

Cuando degraded es true, no se pudo recopilar una parte de la instantánea. La respuesta aún debe tratarse como estado parcial útil, y errors explica que falló.

Devuelve un latido compacto para la instancia de Guida en ejecución.

Use este endpoint para comprobaciones de salud, títulos de ventana, diagnóstico entre pares y tarjetas de estado del tipo “¿Guida está activo?”.

Ventana de terminal
curl http://127.0.0.1:9315/api/dashboard/status

Respuesta de ejemplo:

{
"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
}

Campos importantes:

CampoSignificado
workspaceOpenSi hay un espacio de trabajo abierto
activeWorkflowNameSeleccion actual de flujo de trabajo en el espacio de trabajo
workersRunningAl menos un proceso de trabajo o tarea de una sola ejecución está activo
workersPausedAl menos un grupo de procesos de trabajo está pausado
runningTaskCountNúmero de tareas de script en ejecución
activeRunEjecucion de flujo de trabajo activa, si existe; en caso contrario, la ejecución más reciente
degraded, errorsSi falló una parte de la lectura y por qué
versionVersión monótona de invalidación del panel
applicationVersionVersión semántica de la aplicación Guida, como 0.7.3-alpha.0; no analice metadatos de commit
applicationStartedAtMarca temporal de inicio del proceso
dashboardBindAddress, dashboardPort, dashboardUrlDireccion en la que Guida cree estar sirviendo el panel
nodeIdentity, nodeId, nodeName, nodeRole, machineNameMetadatos estables del nodo para observadores multinodo
workerCountsByStatus, workerRunningCount, workerPausedCount, workerFailedCount, workerIdleCount, workerStoppedCount, workerStalledCountAgregados de estado de grupos de procesos de trabajo

Devuelve una instantánea operativa combinada. Use este endpoint para cargas iniciales de página y acciones de resincronizacion forzada.

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

Parámetros de consulta:

ParámetroTipoSignificado
forceReloadbooleanCuando es true, omite la caché de corta duracion y vuelve a cargar desde la verdad del repositorio o servicio

La instantánea incluye:

CampoSignificado
version, generatedAtIdentidad y marca temporal de la instantánea
workspaceName, workspacePath, activeWorkflowNameContexto actual del espacio de trabajo
queuesFilas de cola acotadas
workerPoolsFilas acotadas de procesos de trabajo
taskCountsByStatusConteos de tareas de script agrupados por estado de tarea
workflowLedgerAgregados completos del registro de trazabilidad de flujos de trabajo
recentRunsLista acotada de ejecuciones recientes
recentFailuresLista acotada de fallos recientes de tareas y ejecuciones
attentionItemsLista acotada de elementos que requieren atención
activeRunResumen de la ejecución activa o más reciente
activeRunReconciliationResumen del traspaso entre captura, análisis e indexación para la ejecución activa
queuePendingCount, queueCheckedOutCount, queueCompletedCount, queueDeadLetterCountTotales completos de cola en todas las colas
queueTotalsByStateTotales de cola agrupados por estado de cola
totalQueueCount, queueLimit, queuesTruncatedLímites de la lista de colas
totalWorkerPoolCount, workerPoolLimit, workerPoolsTruncatedLímites de la lista de procesos de trabajo
workerPoolCountsByStatus, workerPoolRunningCount, workerPoolPausedCount, workerPoolFailedCount, workerPoolIdleCount, workerPoolStoppedCount, workerPoolStalledCountAgregados completos de estado de procesos de trabajo
recentRunsTotalCount, recentRunsLimit, recentRunsTruncatedLímites de la lista de ejecuciones recientes
recentFailuresTotalCount, recentFailuresLimit, recentFailuresTruncatedLímites de la lista de fallos
attentionItemsTotalCount, attentionItemsLimit, attentionItemsTruncatedLímites de la lista de elementos que requieren atención
nodeIdentity, nodeId, nodeName, nodeRole, machineNameMetadatos estables del nodo
degraded, errorsMetadatos de fallo parcial

El objeto workflowLedger contiene datos agregados, no una muestra:

{
"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
}

Los conteos se cargan desde consultas agregadas del repositorio. No se calculan a partir de la primera página de elementos.

Devuelve ejecuciones recientes de flujos de trabajo para el flujo activo.

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

Parámetros de consulta:

ParámetroTipoPredeterminadoMáximoSignificado
takeinteger25100Número de ejecuciones recientes que se deben devolver

Forma de la respuesta:

{
"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": []
}

Devuelve el detalle de una ejecución de flujo de trabajo.

Ventana de terminal
curl http://127.0.0.1:9315/api/dashboard/runs/92d987e072ab4649a5a7f1846446a420

Campos de respuesta:

CampoSignificado
runResumen de la ejecución
stageStateCountsConteos completos por fase y estado de la ejecución
reconciliationResumen del traspaso entre captura, análisis e indexación
attentionItemsMuestra acotada de elementos que requieren atención, limitada a esta ejecución

Si la ejecución no existe, el endpoint devuelve 404.

Devuelve conteos completos agrupados por fase y estado del flujo de trabajo.

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

Respuesta de ejemplo:

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

problemCount es el número de elementos de ese grupo que han fallado, están listos para reintento, están muertos o contienen metadatos de error. Este endpoint es la fuente adecuada para matrices de fase/estado. No está limitado por el tamaño de página de una lista de elementos.

Si la ejecución no existe, el endpoint devuelve 404.

Devuelve filas de cola acotadas y totales completos de cola.

Ventana de terminal
curl http://127.0.0.1:9315/api/dashboard/queues

Campos de respuesta:

CampoSignificado
itemsHasta 100 filas de cola
totalCountNúmero de colas
limitLimite de filas de cola, actualmente 100
truncatedSi se omitieron algunas filas de cola
totalPendingCountElementos pendientes en todas las colas
totalCheckedOutCountElementos tomados/en ejecución en todas las colas
totalCompletedCountElementos completados en todas las colas
totalDeadLetterCountElementos enviados a la cola de rechazos en todas las colas
totalsByStateTotales completos de cola agrupados por estado de cola
degraded, errorsMetadatos de fallo parcial

Cada fila de cola tiene:

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

Devuelve filas acotadas de estado de grupos de procesos de trabajo y conteos agregados de estado.

Ventana de terminal
curl http://127.0.0.1:9315/api/dashboard/workers

Campos de fila de proceso de trabajo:

CampoSignificado
queueCola procesada por este grupo
scriptRuta del script del proceso de trabajo
dequeueStrategyEstrategia opcional de extraccion de cola
concurrencyConcurrencia configurada
activeWorkersBucles de proceso de trabajo en ejecución
processedElementos procesados por el estado actual del grupo
failedElementos fallidos en el estado actual del grupo
remainingElementos restantes de la cola segun el estado del proceso de trabajo
pausedSi el grupo está pausado
activeRunOneCountEjecuciones puntuales activas de procesos de trabajo
statusrunning, paused, stalled, failed, idle o stopped
scopeglobal, workflow o dynamic
checkedOutCountElementos tomados de la cola del grupo

Las definiciones configuradas de procesos de trabajo aparecen aunque esten detenidas. Una definición detenida con elementos tomados de la cola se informa como stalled.

La respuesta también incluye campos agregados:

CampoSignificado
countsByStatusConteos de grupos de procesos de trabajo agrupados por estado
runningCount, pausedCount, failedCount, idleCount, stoppedCount, stalledCountTotales completos de estado de procesos de trabajo
activeWorkerCountSuma de bucles activos de procesos de trabajo
activeRunOneCountSuma de ejecuciones puntuales activas de procesos de trabajo

Devuelve tareas de script fallidas recientes y ejecuciones de flujo de trabajo fallidas.

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

Parámetros de consulta:

ParámetroTipoPredeterminadoMáximoSignificado
takeinteger25100Número de filas de fallo que se deben devolver

Campos de fila de fallo:

CampoSignificado
taskIdID de tarea de script o ID de ejecución de flujo de trabajo
nameNombre de tarea o etiqueta de ejecución de flujo de trabajo
originOrigen de la tarea, como Worker, o WorkflowLedger para ejecuciones fallidas
statusEstado del fallo
startTime, endTimeMarcas temporales de tarea/ejecución
errorMensaje de fallo
queueName, queueItemKey, workerIndexContexto de proceso de trabajo cuando está disponible
mcpToolName, triggerEventContexto MCP/disparador cuando está disponible
kindtask o workflow_run
workflowName, runIdContexto de flujo de trabajo cuando está disponible

Devuelve elementos que requieren atención para el flujo de trabajo activo, o para una ejecución seleccionada cuando se proporciona runId.

Ventana de terminal
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"

Parámetros de consulta:

ParámetroTipoPredeterminadoMáximoSignificado
runIdstringnonen/aLimita la atención a una ejecución
takeinteger50200Número de filas de atención que se deben devolver

Campos de fila de atención:

CampoSignificado
kindexpired_lease, dead_item, failed_item, retry_ready o failed_run
severitycritical, error o warning
workflowName, runIdContexto de flujo de trabajo/ejecución
itemId, itemKeyIdentidad del elemento cuando el elemento de atención se refiere a un item
stage, stateUbicacion del elemento dentro del flujo de trabajo
messageExplicacion breve para el operador
timestampMarca temporal relevante de evento o actualizacion
lastErrorÚltimo error registrado cuando está disponible

Devuelve una conciliación compacta de la canalización para una ejecución de flujo de trabajo.

Ventana de terminal
curl http://127.0.0.1:9315/api/dashboard/reconcile/92d987e072ab4649a5a7f1846446a420

Respuesta de ejemplo:

{
"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"
}

Use este endpoint para responder preguntas de traspaso como:

  • ¿Cuántos elementos de captura siguen en cola, en ejecución, con reserva, omitidos, muertos o listos para reintento?
  • ¿Cuántos elementos de análisis/indexación están en cola?
  • ¿Cuántos elementos de análisis/indexación se completaron?
  • ¿Cuántos elementos de análisis/indexación se recibieron desde captura?
  • ¿Hay una brecha entre captura y análisis, o trabajo pendiente de análisis/indexación?
  • ¿El conteo completo de fase/estado coincide con la forma esperada de la canalización?

Si la ejecución no existe, el endpoint devuelve 404.

Abre un flujo Server-Sent Events para actualizaciones en vivo del panel.

Ventana de terminal
curl -N http://127.0.0.1:9315/api/dashboard/events

El flujo envía solo indicios compactos. No envía instantáneas completas. Un cliente debe tratar los eventos como “algo ha cambiado” y después llamar al endpoint específico que necesite, normalmente /api/dashboard/status, /api/dashboard/snapshot?forceReload=true o un endpoint de ejecución seleccionada.

Evento inicial de conexión:

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"}

Evento de latido:

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"}

Evento de invalidación:

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

Tipos de evento:

EventoSignificado
status con status: "connected"El flujo se abrio correctamente
status con status: "heartbeat"El flujo sigue activo; el intervalo predeterminado de latido es de 15 segundos
invalidationCambio el estado de espacio de trabajo, cola, proceso de trabajo, tarea, registro de trazabilidad de flujos de trabajo o notificaciones

Los eventos de estado incluyen los mismos campos compactos de aplicación, espacio de trabajo e identidad de nodo que /api/dashboard/status. Siguen siendo solo instantáneas de estado, no instantáneas completas del panel.

El canal SSE es acotado. Si llegan muchas invalidaciones rápidamente, Guida puede descartar indicios de invalidación antiguos. Esto es seguro porque los eventos son indicios y los repositorios siguen siendo la fuente de verdad.

EstadoSignificado
200Respuesta JSON correcta o flujo SSE
403Un cliente remoto intentó usar una ruta que no es del panel o un método que no es de lectura
404La ejecución seleccionada no existe, o se solicitó localmente una ruta inexistente como /dashboard
499El cliente se desconecto antes de completar la lectura
503La lectura del panel supero el tiempo de espera
500La lectura del panel falló inesperadamente
  • Use /api/dashboard/status para comprobaciones de vida baratas.
  • Use /api/dashboard/snapshot?forceReload=true para cargas iniciales y resincronizacion explicita.
  • Use /api/dashboard/events para saber cuando recargar estado específico.
  • Use /api/dashboard/runs/{runId}/counts para matrices de fase/estado.
  • Use /api/dashboard/reconcile/{runId} para preguntas de traspaso entre captura y análisis/indexación.
  • Use applicationVersion como version semántica de la aplicación y nodeId como identidad estable del nodo de Guida.
  • Trate las listas acotadas como muestras o páginas; use totalCount, los totales agregados y truncated para tener la imagen completa.
  • No haga polling agresivo mientras haya una conexión SSE abierta. Deje que los eventos de invalidación disparen recargas dirigidas.
  • No asuma que las cargas de eventos son estado duradero. Vuelva a cargar desde los endpoints JSON.