Idempotency

Use Idempotency-Key on supported non-streaming POST requests.

It is optional for these requests:

• POST /v1/conversations
• POST /v1/messages
• POST /v1/conversations/{conversationId}/messages
• POST /v1/embed-sessions

It is required for asynchronous partner-user work:

• POST /v1/integrations/{integration}/user-imports
• POST /v1/integrations/{integration}/users/{external_user_id}/profile-changes
• POST /v1/integrations/{integration}/users/{external_user_id}/deletions
• POST /v1/integrations/{integration}/users/{external_user_id}/reprovision

Behavior

• Matching retries replay the original response or return the same asynchronous operation.
• Reusing a key with a different request body returns 409 idempotency_conflict.
• Treat the idempotency-key namespace as API-key-wide. Never reuse a key for another endpoint, action, or user; a matching retry must use the identical route, target, and payload.
• Reuse a launch key only for a retry of the same launch; every new iframe launch needs a new key.
• Streaming requests do not support Idempotency-Key.

Header format

Generate and persist the key before sending the request. Use a request UUID or a composite value that includes the operation and your immutable external record ID. Do not include an email address, name, or other PII in the key.