Version: 1.0.0

API do Kadu

API multi-tenant para orquestração de agentes.

Autenticação

Toda rota exige Authorization: Bearer <token>, onde o token é um access token RS256 emitido pelo Authorization Server da Kobana (Conta Kobana) para o recurso kadu. O Kadu só verifica o token, com as chaves públicas que o AS publica; não emite token. A organização é a claim org.

Escopos

Os escopos são exigidos em toda rota, exceto GET /v1/me. Cada requisição exige um único nível de acesso, e um nível nunca substitui outro:

Nível	Concede
read	leitura (GET)
write	criação e alteração (POST, PATCH, PUT) — e leitura
delete	remoção (DELETE)
import	importação em massa (nenhum endpoint hoje)
export	exportação em massa (nenhum endpoint hoje)
all	todos os níveis acima

Um token com escopos kadu/{recurso} (ex.: kadu/tasks) fica restrito a esses recursos, e o nível vale só dentro deles; kadu/all alcança todos os recursos. O recurso de uma rota é o primeiro segmento depois de /v1 (/executions/{id}/logs → executions). Recursos: activities, environments, executions, files, memberships, memories, organizations, repository, roles, schedules, secrets, system_events, tasks, todos, usage, users, webhook_deliveries, webhooks, workspaces.

Permissões do usuário

Além dos escopos, um token emitido para uma pessoa (com email) fica limitado ao papel dela na organização (Role.permissions): cada rota exige agent.<recurso>.<ação> (list, read, create, update, delete, e as ações executions.run, webhook_deliveries.replay e repository.sync), com curingas *, agent.* e agent.<recurso>.*. Papel que não concede responde 403 USER_PERMISSION_DENIED (details.required); pessoa sem vínculo com a organização, 403 NOT_A_MEMBER. Token de integração, sem pessoa, vale só pelos escopos. GET /v1/me não confere papel.

Permissões da organização

As rotas de disparo, logs, webhooks, entregas, ambientes, secrets, agendamentos, endpoint da Task, repositório e uso respeitam também as liberações que a Kobana dá à organização para as telas do console. Operação não liberada responde 403 FEATURE_NOT_ENABLED, com details.permission.

Token sem escopo que o Kadu reconheça não alcança nada além do /me. Escopo insuficiente responde 403 INSUFFICIENT_SCOPE, com details.required (os níveis que bastariam).

Contrato

• Wire em snake_case; mapas livres (custom_metadata, payload, parameters…) são opacos.
• Valores monetários e de custo são number (USD em *_usd, reais em *_brl).
• Sucesso: { data } ou { data, meta }; erro: { error: { code, message, details? } } com code em UPPER_SNAKE.
• Listagens por cursor: cursor + limit (máx. 100), ordenação por sort_by + sort_order; meta: { next_cursor, limit }.
• X-Idempotency-Key em todo POST/PUT/PATCH (24h por organização).
• Corpo de POST/PUT/PATCH até 1 MiB; acima disso, 413 PAYLOAD_TOO_LARGE.