API do painel operacional

O Guida expõe uma pequena API operacional somente leitura para monitorar rastreamentos longos e execuções de indexação sem abrir a interface desktop. A API é destinada a scripts, agentes, painéis leves e clientes de monitoramento em rede privada.

Ela não é uma superfície de controle remoto. A API do painel não inicia processos de trabalho, para processos de trabalho, tenta itens novamente, exclui entradas de fila, move trabalho para a fila de rejeitos, executa scripts, navega guias nem chama ferramentas MCP.

Use a API de operações remotas quando um cliente de rede privada precisar de controle remoto explícito. Use esta API do painel quando o cliente só precisar observar estado.

Para estruturas de teste determinísticas com endpoints de automação protegidos por token, use Modo de automação. Para ferramentas locais de IA com aprovações e registro de auditoria, use Integração MCP.

URL base

Por padrão, o servidor embutido escuta em loopback:

http://127.0.0.1:9315

Quando um endereço privado seguro de bind é configurado em Settings, o Guida mantém loopback disponível e também expõe a API do painel somente leitura nesse endereço privado. Isso é útil para monitoramento por NetBird ou LAN, por exemplo:

http://100.68.25.200:9315

O conteúdo de status inclui dashboardUrl, dashboardBindAddress, dashboardPort, applicationVersion e campos estáveis de identidade do nó para que o cliente exiba o endereço e o nó Guida monitorado.

Modelo de segurança

A API do painel é deliberadamente mais estreita que o MCP.

Cliente	Permitido
Cliente local loopback	MCP mais pontos de extremidade do painel
Cliente remoto de rede privada	Apenas pontos de extremidade do painel somente leitura
`POST`, `PUT`, `DELETE` etc. remotos em caminhos do painel	Rejeitados
Caminhos MCP remotos de rede privada	Rejeitados
`/api/ops/*` remoto de rede privada	Disponível apenas quando a API de operações remotas está explicitamente habilitada
Bind wildcard público como `0.0.0.0`	Rejeitado pela validação de configurações

Clientes remotos do painel devem usar solicitações GET. HEAD também é tratado como somente leitura. Preflight OPTIONS só é aceito quando o método solicitado é somente leitura.

Chamadas de ferramentas MCP usam POST na superfície MCP local. Operações remotas usam POST /api/ops/rpc apenas quando esse recurso está habilitado. Clientes do painel não devem usar POST; não há mutações de painel nesta API.

Endereços seguros de bind incluem loopback, faixas IPv4 privadas RFC1918, NetBird/CGNAT 100.64.0.0/10, IPv4 link-local, IPv6 unique local e IPv6 link-local. Endereços wildcard e públicos voltam para loopback.

Todas as leituras do painel definem cabeçalhos no-cache. Leituras de instantâneo são protegidas por tempo limite curto; uma leitura lenta retorna uma resposta problem 503 em vez de travar indefinidamente o trabalho de rastreamento.

Resumo dos pontos de extremidade

Todos os pontos de extremidade principais ficam em /api/dashboard.

Ponto de extremidade	Finalidade
`GET /api/dashboard/status`	Sinal de vida compacto de app, espaço de trabalho, fluxo, execução ativa, processos de trabalho e runtime
`GET /api/dashboard/snapshot`	Instantâneo operacional combinado e limitado
`GET /api/dashboard/runs`	Execuções recentes de fluxos de trabalho
`GET /api/dashboard/runs/{runId}`	Detalhe de uma execução
`GET /api/dashboard/runs/{runId}/counts`	Contagens completas estágio/estado da execução
`GET /api/dashboard/queues`	Contagens de filas e totais
`GET /api/dashboard/workers`	Status de grupos de processos de trabalho
`GET /api/dashboard/failures`	Motivos recentes de tarefas e execuções com falha
`GET /api/dashboard/attention`	Itens atuais que exigem atenção
`GET /api/dashboard/reconcile/{runId}`	Resumo de passagem fetch/parse/index para uma execução
`GET /api/dashboard/events`	Fluxo Server-Sent Events para invalidação ao vivo e sinal de vida

Convenções de resposta

Propriedades JSON usam camel case.

Muitos pontos de extremidade retornam listas limitadas. Uma resposta de lista limitada usa este envelope:

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

Quando truncated é true, o ponto de extremidade retornou a primeira página ou amostra limitada, mas totalCount ainda informa a contagem total conhecida pelo repositório/serviço. Para perguntas agregadas, use os campos agregados, não o tamanho de items.

Quando degraded é true, parte do instantâneo não pôde ser coletada. A resposta ainda deve ser tratada como estado parcial útil, e errors explica o que falhou.

`GET /api/dashboard/status`

Retorna um sinal de vida compacto da instância Guida em execução.

Use este ponto de extremidade para verificações leves de vida, títulos de janela, diagnóstico de pares e cartões “o Guida está vivo?”.

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

Campos importantes:

Campo	Significado
`workspaceOpen`	Se um espaço de trabalho está aberto
`activeWorkflowName`	Seleção atual de fluxo do espaço de trabalho
`workersRunning`	Ao menos um processo de trabalho ou tarefa run-one está ativo
`workersPaused`	Ao menos um grupo de processos de trabalho está pausado
`runningTaskCount`	Número de tarefas de script em execução
`activeRun`	Execução de fluxo em andamento, se houver; caso contrário, a execução mais recente
`degraded`, `errors`	Se parte da leitura falhou e por quê
`version`	Versão monotônica de invalidação do painel
`applicationVersion`	Versão semântica do app Guida, como `0.7.3-alpha.0`; não analise metadados de commit
`applicationStartedAt`	Timestamp de início do processo
`dashboardBindAddress`, `dashboardPort`, `dashboardUrl`	Endereço em que o Guida acredita estar servindo o painel
`nodeIdentity`, `nodeId`, `nodeName`, `nodeRole`, `machineName`	Metadados estáveis do nó para observadores multi-nó
`workerCountsByStatus`, `workerRunningCount`, `workerPausedCount`, `workerFailedCount`, `workerIdleCount`, `workerStoppedCount`, `workerStalledCount`	Agregados de status dos grupos de processos de trabalho

`GET /api/dashboard/snapshot`

Retorna um instantâneo operacional combinado. Use para carregamentos iniciais de página e ações de ressincronização forçada.

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

Parâmetros de consulta:

Parâmetro	Tipo	Significado
`forceReload`	boolean	Quando `true`, ignora o cache curto e recarrega da verdade do repositório/serviço

O instantâneo inclui contexto de espaço de trabalho, filas, grupos de processos de trabalho, contagens de tarefas, agregados do registro de rastreabilidade, execuções recentes, falhas, itens de atenção, execução ativa, reconciliação da execução ativa, totais de filas, totais de processos de trabalho, metadados de nó e campos degraded/errors.

O objeto workflowLedger é dado agregado, não amostra:

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

Contagens vêm de consultas agregadas do repositório. Elas não são calculadas a partir da primeira página de itens.

Execuções

GET /api/dashboard/runs retorna execuções recentes para o fluxo ativo:

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

take tem padrão 25 e máximo 100.

GET /api/dashboard/runs/{runId} retorna detalhe de uma execução: resumo, contagens estágio/estado da execução inteira, reconciliação e amostra limitada de atenção. Se a execução não existir, retorna 404.

GET /api/dashboard/runs/{runId}/counts retorna contagens agrupadas por estágio e estado:

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

problemCount é o número de itens naquele grupo que falharam, estão prontos para nova tentativa, mortos ou carregam metadados de erro. Este ponto de extremidade é a fonte correta para matrizes de estágio/estado. Ele não é limitado pelo tamanho de página da lista de itens.

Filas e processos de trabalho

GET /api/dashboard/queues retorna linhas de filas limitadas e totais completos de fila:

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

Campos incluem items, totalCount, limit, truncated, totalPendingCount, totalCheckedOutCount, totalCompletedCount, totalDeadLetterCount, totalsByState, degraded e errors.

Cada linha de fila inclui nome, contagens por estado, pendentes, retirados, concluídos e rejeitados.

GET /api/dashboard/workers retorna linhas limitadas de status de grupos e contagens agregadas por status:

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

Linhas de processos de trabalho incluem fila, script, estratégia de retirada opcional, concorrência, processos ativos, processados, falhas, restantes, paused, run-one ativo, status, escopo e contagem retirada. Definições configuradas aparecem mesmo quando paradas. Uma definição parada com itens retirados é relatada como stalled.

Falhas e atenção

GET /api/dashboard/failures retorna tarefas de script falhas recentes mais execuções de fluxo com falha:

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

take tem padrão 25 e máximo 100. Linhas de falha incluem ID, nome, origem, status, timestamps, erro, contexto de processo de trabalho, MCP ou gatilho quando disponível, e contexto de workflow quando disponível.

GET /api/dashboard/attention retorna itens de atenção para o fluxo ativo ou para uma execução selecionada quando runId é informado:

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"

Itens de atenção têm kind, severity, contexto de workflow/execução, identidade do item, estágio/estado, mensagem curta ao operador, timestamp e último erro quando disponível.

`GET /api/dashboard/reconcile/{runId}`

Retorna reconciliação compacta de fluxo para uma execução:

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

Use este ponto de extremidade para responder perguntas de passagem:

Quantos itens de fetch ainda estão em fila, em execução, com lease, ignorados, mortos ou prontos para nova tentativa?
Quantos itens de parse/index estão em fila?
Quantos itens de parse/index foram concluídos?
Quantos itens de parse/index foram recebidos de fetch?
Há lacuna fetch-para-parse ou acúmulo de parse/index?
A contagem completa de estágio/estado corresponde ao formato esperado do fluxo?

Se a execução não existir, o ponto de extremidade retorna 404.

`GET /api/dashboard/events`

Abre um fluxo Server-Sent Events para atualizações ao vivo do painel.

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

O fluxo envia apenas dicas compactas. Ele não envia instantâneos completos. Um cliente deve tratar eventos como “algo mudou” e então chamar o ponto de extremidade focado de que precisa, normalmente /api/dashboard/status, /api/dashboard/snapshot?forceReload=true ou um ponto de extremidade de execução selecionada.

Tipos de evento:

Evento	Significado
`status` com `status: "connected"`	Fluxo aberto com sucesso
`status` com `status: "heartbeat"`	Fluxo ainda vivo; intervalo padrão do sinal de vida é 15 segundos
`invalidation`	Estado de espaço de trabalho, fila, processo de trabalho, tarefa, registro de rastreabilidade ou notificação mudou

Eventos de status incluem os mesmos campos compactos de app/espaço de trabalho/identidade do nó que /api/dashboard/status. Eles ainda são apenas instantâneos de status, não instantâneos completos do painel.

O canal SSE é limitado. Se muitas invalidações chegam rapidamente, o Guida pode descartar dicas antigas. Isso é seguro porque eventos são dicas e os repositórios continuam sendo a fonte da verdade.

Códigos de status

Status	Significado
`200`	Resposta JSON ou fluxo SSE bem-sucedido
`403`	Cliente remoto tentou caminho que não é do painel ou método que não é leitura
`404`	Execução selecionada não existe ou rota inexistente como `/dashboard` foi solicitada localmente
`499`	Cliente desconectou antes da leitura terminar
`503`	Leitura do painel excedeu o tempo limite
`500`	Leitura do painel falhou inesperadamente

Orientação para clientes

Use /api/dashboard/status para verificações leves de vida.
Use /api/dashboard/snapshot?forceReload=true para carregamentos iniciais e ressincronização explícita.
Use /api/dashboard/events para saber quando recarregar estado focado.
Use /api/dashboard/runs/{runId}/counts para matrizes de estágio/estado.
Use /api/dashboard/reconcile/{runId} para perguntas de passagem fetch-para-parse/index.
Use applicationVersion como versão semântica do app e nodeId como identidade estável do nó Guida.
Trate listas limitadas como amostras ou páginas; use totalCount, totais agregados e truncated para o quadro completo.
Não faça polling agressivo com uma conexão SSE aberta. Deixe eventos de invalidação dispararem recargas direcionadas.
Não presuma que conteúdos de eventos sejam estado durável. Recarregue pelos pontos de extremidade JSON.

Próximos passos

Integração MCP - acesso local a ferramentas MCP, aprovações e registro de auditoria
API de operações remotas - controle remoto por canal confiável sobre JSON-RPC
Registro de rastreabilidade dos fluxos de trabalho - execuções, itens, contagens estágio/estado e reconciliação duráveis
Processos de trabalho das filas - grupos de processos baseados em fila e processamento em lote
Filas e revisão - inspeção de filas e triagem de operador