Idempotency

Pass idempotencyKey on createTask and we guarantee at most one admission for that key per workspace within a 1-hour window.

POST /createTask
{
  "clientKey": "cai_…",
  "idempotencyKey": "order-9382-attempt-1",
  "task": { ... }
}

Subsequent calls with the same key return the original taskId plus "idempotent": true — no second thread is consumed.

What counts as "same"?

Only the idempotencyKey value is matched. The task payload is not compared. If you change the payload but reuse the key you will get the original task's taskId back regardless.

TTL

Keys are remembered for 1 hour after the original admission. After that the key is reusable — typically long enough for any retry storm to have drained.

When to use it

• Webhook receivers that may redeliver
• Cron jobs whose run id you want to attach
• Batch importers that retry on network failure

Do not use it as a deduplication key for user input — generate a fresh UUID per logical task instead.