Idempotency

The tools that change data — all of them except the read and delete tools — accept an optional idempotency_key argument. It is sent to the route as the X-Idempotency-Key header the v1 API already honors, and the rules are the API's (see API idempotency).

{ "name": "kadu_tasks_run",
  "arguments": {
    "id": "2f1c…",
    "environment_id": "8a40…",
    "reference_date": "2026-10-30",
    "idempotency_key": "run-2026-10-30-boleto-payments"
  } }

Format	Opaque text, 1 to 255 characters.
Validity	24 hours, within the organization.
Repeat with the same arguments	Returns the original response, without running the operation again.
Repeat with different arguments	isError with IDEMPOTENCY_KEY_REUSED.
Repeat while the first is still running	isError with IDEMPOTENCY_REQUEST_IN_PROGRESS; try again in a few seconds, with the same key.

The repeat returns the same body as the first call. The API's X-Idempotent-Replay header does not reach the tool result, which carries only the body. A secret shown only once — the signing secret from kadu_webhooks_create and kadu_webhooks_rotate_secret — comes back null on the repeat.

Why an agent needs this more than your backend

An MCP client that times out and retries, or a model that decides "I am not sure that worked, I will do it again", is exactly the pattern that queues the second execution, replays the same delivery twice or creates the second schedule. Your backend has a retry loop you wrote; the agent has judgment.

Generate one key per business operation (for example, run-<date>-<task>), not per attempt: it is the same key on every retry that makes the retry safe.

Tools that accept it

Family	Tools
Organization and structure	kadu_organizations_update, kadu_workspaces_create, kadu_workspaces_update, kadu_activities_create, kadu_activities_update, kadu_tasks_create, kadu_tasks_update, kadu_tasks_endpoint_update
Executions	kadu_tasks_run, kadu_executions_cancel, kadu_executions_continue, kadu_todos_update
Memories	kadu_memories_create, kadu_memories_update
Configuration	kadu_environments_create, kadu_environments_update, kadu_secrets_create, kadu_secrets_update, kadu_schedules_create, kadu_schedules_update
Files and Playbook	kadu_files_create, kadu_files_confirm, kadu_repository_sync
Webhooks	kadu_webhooks_create, kadu_webhooks_update, kadu_webhooks_rotate_secret, kadu_webhook_deliveries_replay
Roles	kadu_roles_create

The delete tools do not accept it: deleting the same record again already answers NOT_FOUND, with no effect at all.

:::caution The ones that run the agent kadu_tasks_run and kadu_executions_continue queue an execution, and the agent acts on the task's systems — banking, ERP, invoices — with effects no delete undoes. kadu_webhook_deliveries_replay delivers again to the receiver's system. Send idempotency_key on these even when you think you will not repeat. :::

Idempotency and confirmation

Every call of a destructive tool asks for your confirmation again: a client that repeats the call after a timeout produces a second question, or a second approval link. With the same idempotency_key on both, confirming both does not run the task twice — the second returns the first one's response.