Referência da API

Esta seção descreve a superfície pública do VolundOS: disparar agentes, acompanhar execuções e operar a governança de ativos a partir do seu próprio código.

Ela é derivada do contrato, e não escrita à parte: cada página nasce da mesma especificação que o servidor cumpre, e um teste no repositório da plataforma recusa a mudança em que uma rota nova aparece sem documentação — ou em que uma operação documentada deixa de existir.

Como autenticar

Toda chamada leva uma chave de API no cabeçalho:

Authorization: Bearer <sua chave>

A chave é criada nas configurações da organização, e é lá também que se escolhe o que ela alcança. Duas coisas valem a pena entender antes da primeira chamada:

• A chave enxerga o que a pessoa dona dela enxerga. Ela não é um passe administrativo: o mesmo controle de acesso que vale na tela vale aqui.
• Cada operação exige um escopo, e o escopo aparece na descrição de cada uma. Uma chave sem o escopo recebe 403 com a lista do que faltou, em vez de um erro genérico.

A criação de chaves, os escopos disponíveis e a restrição por agente estão descritos em Chaves de API.

Como os erros chegam

Toda falha responde com o mesmo formato — um código estável em error, para o seu código decidir, e uma frase em message, para quem lê o log:

{ "error": "insufficient_scope", "message": "..." }

Algumas trazem contexto adicional: insufficient_scope inclui os escopos exigidos, e agent_not_allowed inclui o agente recusado.

Duas famílias

Execução cobre o ciclo de um agente: disparar, acompanhar o passo a passo, continuar a conversa e decidir aprovações pendentes.

Governança cobre o inventário de ativos externos e o que se faz em cima dele: reportar métricas, configurar monitores, consultar alertas, promover entre ambientes e receber webhooks.