Skip to main content

Authentication

Send your secret as a bearer token:
The key identifies the organization, domain, and allowed scopes. Do not send identity headers: the API derives identity from the key.

Least-privilege scopes

Idempotency

Every mutating V1 request requires a unique Idempotency-Key. Replaying the same key with the same payload returns the same logical result without applying the change twice. Reusing a key for a different payload is rejected. Keep keys stable when retrying a request after a timeout. Generate a new key for a new business action. Use the same key and the same payload to recover the result of a timed-out call without creating another turn. Idempotency does not replace optimistic concurrency with state_version.

Optimistic concurrency

Mutations to an existing session include state_version. After a successful mutation, replace your stored value with the version returned by the API. If two workers write from the same version, only one can succeed. On 409 state_version_conflict, read the session again and decide whether the second action still applies.
Do not automatically retry a state conflict with a new version without checking the business action. This could apply an obsolete answer to a newer conversation state.