Information
- OpenAPI version:
3.1.0
Workspace-scoped API for users, conversations, messages, events, and webhooks.
Send Authorization: Bearer optlo_live_<keyId>_<secret>. Workspace admins create and manage keys in Settings → API keys. Write scopes do not imply read scopes.
JSON request bodies are limited to 64 KiB, including streamed requests; larger bodies return 413 payload_too_large. Unknown and repeated query parameters are rejected. All timestamps are UTC ISO-8601. Responses may gain additive fields; clients must tolerate extensible enums.
Lists sort by creation time and ID descending; messages sort by sequence descending. Pagination is not snapshot-consistent. Conversation lists use an eventually consistent inbox replica; details and messages use authoritative storage. Greeting-only conversations and retracted messages are excluded. Message bodies require message or note scopes; conversation resources never include bodies.
Approximate per-location limits are 120 requests/minute/key, 1,200/workspace, and 600 authentication attempts/minute/IP. Cloudflare enforcement is eventually consistent and can overshoot; no exact remaining request-rate quota is advertised.
Each user also accepts at most 30 messages and notes per minute across all of their conversations, and 10 per minute from any one sender, counting every channel. Requests beyond that return 429 rate_limited after the message allowance is consumed; retry with the same Idempotency-Key so it is not consumed again.
Write allowances are shared across workspace keys and count admitted writes over a rolling 24 hours, measured in hourly buckets:
| Resource | Trial / no paid subscription | Paid subscription |
|---|---|---|
| Users | 100 | 10,000 |
| Conversations | 50 | 1,000 |
| Messages, including notes | 200 | 5,000 |
Conversation creation consumes one conversation and one message. Each unique admitted operation counts, including when a later step fails. Retained idempotent retries consume no additional capacity. Widget, dashboard, inbound email, and automatic workflow output do not count. Plan changes preserve usage.
Exhaustion returns 429 daily_limit_exceeded with details: { resource, limit, used, retryAt } and Retry-After until retryAt, the earliest time enough older writes leave the window for usage to drop below the limit. These allowances are independent of existing billing limits and workspace-pause rules.
Webhook subscriptions can be managed through the API and dashboard. Active subscriptions receive matching events asynchronously, with at-least-once delivery.
Security scheme type: http
Bearer format: optlo_live_<keyId>_<secret>