Idempotency

Any POST / PATCH / PUT / DELETE on /v1 can carry an Idempotency-Key header:

POST /v1/projects
Idempotency-Key: key-2026-04-23-creat-demo-project

On the first call we execute and cache the response for 24 hours. On a retry with the same key and the same body, we return the cached response with an extra Idempotent-Replayed: true header. On a retry with the same key and a different body, we return 409 idempotency_key_reused so your client can't accidentally apply the wrong state because of a mix-up.

Keys must be 1–255 URL-safe characters (alphanumeric, underscore, hyphen).

SDK support

@exayard/sdk auto-generates an Idempotency-Key for every unsafe method. Pin your own when you want to safely retry from a persistent queue:

await exa.projects.create(
  { organizationId, name: 'Demo' },
  { idempotencyKey: `queue-job-${jobId}` }
)