Run endpoint

The run endpoint lets another system run one specific task with an HTTP POST, without a Kobana Account token: each task has its own URL and its own credential. It is the path for an ERP, a form or a third-party webhook to trigger Kadu.

POST https://api.kadu.ia.br/run-task/{task_id}

Staging: https://api.staging.kadu.ia.br/run-task/{task_id}. Each task's URL appears in Settings → Endpoints, with a call example.

Enable

A task's endpoint is enabled by the Playbook (task.endpoint), and the credential is registered in Kadu, never in the Playbook. See Endpoints and Schedule, endpoint and executor.

Authentication

One of four, according to the task's configuration:

Type	How to send
HTTP Basic	Authorization: Basic <base64(user:password)>
Bearer Token	Authorization: Bearer <token>
Header	the configured header, with the configured value (X-Api-Key: …)
URL parameter	?<name>=<value> in the URL. Avoid: the URL appears in proxy logs.

Body

curl -X POST "https://api.kadu.ia.br/run-task/2f1c…" \
  -H "Authorization: Bearer $TASK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-48213" \
  -d '{
    "environment_id": "8a40…",
    "reference_date": "2026-10-30",
    "parameters": { "pedido": "48213" },
    "locale": "pt-BR"
  }'

Field	Required	Rule
environment_id	yes	UUID of the environment the task runs in
reference_date	no	YYYY-MM-DD; default: today's date
parameters	no	object validated against the task's parameters_schema; default {}
locale	no	execution language (pt-BR, en)
additional_instructions	no	free text sent to the agent along with the skill, up to 8,000 characters

The body is JSON only, up to 1 MiB: a task triggered through the endpoint does not receive input files.

Responses

201 when the execution was created. It joins the task's queue and starts on its own:

{ "execution_id": "c7d2…", "status": "queued" }

Response	When
400 validation_failed	body outside the format above
401 unauthorized	credential missing or wrong
403 ENTITLEMENT_REQUIRED	the organization does not have Kadu in its plan
404 not_found	task does not exist, was removed or has the endpoint disabled. The response is the same in all three cases, so as not to reveal whether the task exists.
409	X-Idempotency-Key conflict (Idempotency)
413 payload_too_large	body above 1 MiB
422 unprocessable_entity	parameters did not pass parameters_schema (details carries the errors)
422 environment_required	environment_id missing or invalid
422 missing_secrets	secrets required by the task with no value in the environment (details says which)
422 cost_limit_reached	the organization reached the monthly cost cap
429 rate_limited	more than 60 calls per minute from the same IP for the same task

With X-Idempotency-Key, repeating the same call returns the original response with X-Idempotent-Replay: true, without creating another execution.

To know when the execution finished, subscribe to execution.completed and execution.failed in the webhooks.

Autonomous Inbox webhook

The endpoint directly receives Kobana's Autonomous Inbox webhook. A delivery with the X-Kobana-App: inbox header carries the Inbox envelope in place of the body above, and Kadu converts it:

• data.email becomes the parameters, filtered by the properties of the task's parameters_schema (with no schema, the whole object goes);
• the delivered_at date becomes the reference_date;
• the environment comes from the query, because the Inbox does not let you change the body.

Register in the Inbox the URL https://api.kadu.ia.br/run-task/{task_id}?environment_id=<uuid> and configure the Inbox webhook's optional authentication (Basic, Bearer or header) with the task's credential.