Convenciones

Formato

La API acepta y responde JSON. Envía Content-Type: application/json en toda solicitud con cuerpo.

Tipo	Formato
Nombres de campo	snake_case, en ambos sentidos
Fecha y hora	ISO 8601 en UTC: 2026-10-31T12:00:00.000Z
Fecha	AAAA-MM-DD (por ejemplo, la reference_date de una ejecución)
Identificadores	UUID
Costo	number en dólares, en los campos que terminan en _usd
Precio	number en reales, en los campos que terminan en _brl
Mapas libres	custom_metadata, payload, parameters… son opacos: las claves vuelven tal como se guardaron

Envelope

Éxito de un recurso:

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

Éxito de un listado:

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

Error:

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

code es estable, en UPPER_SNAKE_CASE: es el que tu código debe comparar, y no el message. Ver Errores.

Cuerpo de las escrituras

• POST, PUT y PATCH aceptan un cuerpo de hasta 1 MiB. Por encima de eso, la respuesta es 413 PAYLOAD_TOO_LARGE.
• PATCH modifica solo los campos enviados.
• Toda escritura acepta X-Idempotency-Key (Idempotencia).

metadata y custom_metadata

custom_metadata es tuyo: un objeto libre que guardas y lees en organización, workspace, actividad, tarea y memoria. system_metadata es de Kadu y es de solo lectura.

Eliminación

DELETE no borra la fila: el recurso recibe deleted_at y desaparece de las lecturas. Eliminar de nuevo el mismo recurso responde 404.

Lanzamiento de una tarea

POST /v1/tasks/{id}/run responde 201 con el id de la ejecución creada: { "data": { "execution_id": "…", "status": "queued" } }. La ejecución entra en la cola de la tarea y empieza sola (Ejecuciones). Síguela con GET /v1/executions/{id}, con sus /events y /logs, o con los webhooks.

Antes de lanzar, GET /v1/tasks/{id}/readiness?environment_id=… responde si el entorno tiene todos los secrets que exige la tarea, sin crear nada.