Convenções

Formato

A API aceita e responde JSON. Envie Content-Type: application/json em toda requisição com corpo.

Tipo	Formato
Nomes de campo	snake_case, nos dois sentidos
Data e hora	ISO 8601 em UTC: 2026-10-31T12:00:00.000Z
Data	AAAA-MM-DD (por exemplo, a reference_date de uma execução)
Identificadores	UUID
Custo	number em dólares, nos campos terminados em _usd
Preço	number em reais, nos campos terminados em _brl
Mapas livres	custom_metadata, payload, parameters… são opacos: as chaves voltam como foram gravadas

Envelope

Sucesso de um recurso:

{ "data": { "id": "2f1c…", "label": "Baixar pagamentos" } }

Sucesso de uma listagem:

{
  "data": [ { "id": "2f1c…" }, { "id": "8a40…" } ],
  "meta": { "next_cursor": "eyJpZCI6…", "limit": 25 }
}

Erro:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sort_order deve ser asc ou desc",
    "details": {}
  }
}

code é estável, em UPPER_SNAKE_CASE: é ele que o seu código deve comparar, e não a message. Ver Erros.

Corpo das escritas

• POST, PUT e PATCH aceitam corpo de até 1 MiB. Acima disso, a resposta é 413 PAYLOAD_TOO_LARGE.
• PATCH altera só os campos enviados.
• Toda escrita aceita X-Idempotency-Key (Idempotência).

metadata e custom_metadata

custom_metadata é seu: um objeto livre que você grava e lê em organização, workspace, atividade, tarefa e memória. system_metadata é do Kadu e é só de leitura.

Remoção

DELETE não apaga a linha: o recurso ganha deleted_at e some das leituras. Remover de novo o mesmo recurso responde 404.

Disparo de uma tarefa

POST /v1/tasks/{id}/run responde 201 com o id da execução criada: { "data": { "execution_id": "…", "status": "queued" } }. A execução entra na fila da tarefa e começa sozinha (Execuções). Acompanhe por GET /v1/executions/{id}, pelos /events e /logs dela, ou pelos webhooks.

Antes de disparar, GET /v1/tasks/{id}/readiness?environment_id=… responde se o ambiente tem todos os secrets que a tarefa exige, sem criar nada.