Any endpoint that mutates billing or persists a one-shot side-effect (cap-topup, cap-remove, adjust-credits, publish, knowledge upload) accepts an idempotencyKey field. Pass a UUID per logical operation; re-runs become safe no-ops. Critical for retries through unreliable networks.

Always treat PATCH /apps/{id} as a draft change. Use GET /apps/{id} → hasPendingPublish to detect changes that aren't live yet and decide whether to surface an "Apply your changes" prompt. Don't assume edits are live until you've taken the assistant live.

• Store API tokens in env vars or a secrets manager
• Never commit them to version control
• Never expose them to client-side JavaScript
• Rotate periodically — contact support@everycallhandled.com for a new token, or revoke and re-mint scoped keys yourself
• Request (or mint) the minimum access you need — a capability-scoped key beats a broad token for single-purpose integrations

If you set postChatCallback, your endpoint should:

• Return 200 quickly (within 5s); do heavy processing asynchronously
• Be idempotent — the platform may retry
• Verify the signature (and check the Authorization header matches the value you supplied)

Soft per-account limits apply (~100 req/min steady-state, burst higher). If you anticipate sustained higher load (e.g. bulk migration), email support@everycallhandled.com and we'll raise the limit.

For asynchronous operations (knowledge upload, going live):

• Initial poll: ~3 seconds after the request
• Subsequent polls: every 3-5 seconds
• Give up after 5 minutes for knowledge jobs, 30 seconds for going live