Reference Overview
This is the developer-facing section of the docs. If you are wiring Omniflow into an existing system, building a custom integration, debugging a production incident, or extending the voice runtime, this is your starting point. The pages here are intentionally terse and dense — they assume you’ve read the relevant feature pages elsewhere in the docs and now you need the contract.
What’s in this section
When to use which
| If you need to… | Go to |
|---|---|
| Read or write Omniflow data from your code | API Reference |
| React to events as they happen in Omniflow | Webhooks |
| Understand the audio pipeline, latency, and failover | Voice Runtime |
| Diagnose a specific error message or symptom | Troubleshooting |
The split is simple: API is you call us, Webhooks is we call you, Voice Runtime is how the audio plumbing actually works, and Troubleshooting is what to do when something is wrong.
Authentication at a glance
Every API and webhook flow shares the same auth model:
- API keys are workspace-scoped, generated under Settings → API Keys, and passed as
Authorization: Bearer <key>. - Webhook signatures are HMAC-SHA256 over the raw request body, sent as
X-Omniflow-Signature. Always verify before trusting payload contents. - OAuth is used by integrations (Salesforce, HubSpot, Gmail, etc.) — not for direct API access.
- SSO/SCIM governs human access to the app, not API access.
Treat API keys as service-role credentials. They bypass RLS and can read every conversation in the workspace. Rotate on a schedule, scope per-system, and never commit them.
Rate limits at a glance
| Surface | Default limit | Notes |
|---|---|---|
| REST API | 600 req/min per workspace | Burst to 1200/min for 30s; 429 when exceeded with Retry-After. |
| Webhooks (outbound) | Best-effort, retried with exponential backoff | 5 retries over ~30 minutes; failures land in the dead-letter view. |
| Voice runtime | Negotiated per deployment | See Voice Runtime. |
Higher limits are available on Enterprise plans — see Deployment Options.
Versioning policy
The REST API uses date-based versioning (Omniflow-Version: 2025-11-01). Breaking changes ship under a new version date and the previous version is supported for a minimum of 12 months. Webhooks include the version they were sent under so you can pin handlers.
The voice runtime is versioned per-region and rolls forward with announced maintenance windows.
Setup at a glance
If you’re wiring Omniflow into your stack for the first time:
- Create an API key. Settings → API Keys. Scope it to the smallest set of permissions you need.
- Make your first call. The “Hello, Omniflow” example in API Reference — list your conversations.
- Subscribe to webhooks. Pick the events you need from Webhooks. Verify signatures from day one.
- Wire up monitoring. Surface 4xx and 5xx response rates and webhook delivery failures in your existing observability stack.
- When something breaks → Troubleshooting.
Where to go next
| If you want to… | Go to |
|---|---|
| Build a custom agent tool | Tools & Actions |
| Expose your system as an Omniflow integration | Custom API & Webhooks |
| Understand voice latency targets | Voice Runtime |
| Read the security posture for compliance review | Security & Compliance |