Conventions

Format

The API accepts and responds with JSON. Send Content-Type: application/json on every request with a body.

Type	Format
Field names	snake_case, in both directions
Date and time	ISO 8601 in UTC: 2026-10-31T12:00:00.000Z
Date	YYYY-MM-DD (for example, an execution's reference_date)
Identifiers	UUID
Cost	number in dollars, in fields ending in _usd
Price	number in reais, in fields ending in _brl
Free-form maps	custom_metadata, payload, parameters… are opaque: keys come back as they were stored

Envelope

Success for a resource:

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

Success for a listing:

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

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sort_order must be asc or desc",
    "details": {}
  }
}

code is stable, in UPPER_SNAKE_CASE: it is what your code should compare, not message. See Errors.

Write bodies

• POST, PUT and PATCH accept a body of up to 1 MiB. Above that, the response is 413 PAYLOAD_TOO_LARGE.
• PATCH changes only the fields sent.
• Every write accepts X-Idempotency-Key (Idempotency).

metadata and custom_metadata

custom_metadata is yours: a free-form object that you write and read on organization, workspace, activity, task and memory. system_metadata belongs to Kadu and is read-only.

Removal

DELETE does not erase the row: the resource gets deleted_at and disappears from reads. Removing the same resource again responds 404.

Running a task

POST /v1/tasks/{id}/run responds 201 with the id of the created execution: { "data": { "execution_id": "…", "status": "queued" } }. The execution joins the task's queue and starts on its own (Executions). Follow it through GET /v1/executions/{id}, its /events and /logs, or the webhooks.

Before running, GET /v1/tasks/{id}/readiness?environment_id=… tells you whether the environment has all the secrets the task requires, without creating anything.