Referência da API

Esta seção descreve a superfície pública do VolundOS: disparar agentes e esteiras, acompanhar execuções, operar a governança de ativos, administrar as pessoas e os times da organização, manter as bases que os agentes leem e sustentar uma aplicação que age em nome de quem a usa — tudo 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.

As famílias

Execução cobre o ciclo de um agente: disparar, acompanhar o passo a passo, continuar a conversa, decidir aprovações pendentes e responder às perguntas que o agente abre no meio do trabalho.

Pipelines cobre as esteiras de agentes: disparar, acompanhar o progresso etapa por etapa e cancelar uma execução em andamento.

Governança cobre o inventário de ativos de IA externos — registrar um ativo, listar o que já existe e detalhar um deles — e o consumo desses sistemas: enviar o que foi gasto, ler o acumulado e abrir por assento ou por projeto. Cobre também as unidades de negócio, que repartem o gasto de cada pessoa entre as áreas a que ela pertence: criar e manter as unidades, e dizer em que proporção cada pessoa entra em cada uma.

Contas vinculadas é chamada com a credencial da pessoa, e não com a chave da organização: uma aplicação registrada age em nome de cada pessoa que vinculou a conta a ela.

Agentes do app devolve os agentes que uma aplicação publicada oferece a quem a usa.

Times cobre os subgrupos da organização: criar e manter um time, gerenciar quem está nele e com que papel, e dar ao time acesso compartilhado a agentes e a bases de conhecimento.

Conhecimento cobre as bases que os agentes leem: criar e manter uma base, escrever e ler documentos dentro dela, mover documentos entre bases e escolher quais agentes a enxergam.

Leaderboard devolve o ranking de consumo da própria organização, para que outra organização possa exibi-lo no painel dela. Dá para escolher a janela de tempo e se o ranking é por pessoa, por sistema ou por time.

Pessoas cobre quem está na organização: listar, trocar o perfil de acesso, suspender e reativar, remover — e os convites, que se mandam, reenviam e cancelam. Antes de tirar alguém, dá para ver tudo o que é dessa pessoa na organização e passar para outra as bases, as esteiras, as skills pessoais, os artefatos, os gatilhos e a gestão dos times em que ela era a única gestora. O inventário mostra mais do que isso — agentes, integrações da conta dela, convites pendentes —, e esses não se transferem por aqui.