API Reference

The Omniflow REST API covers everything you can do in the UI plus a few things you can’t (bulk export, server-side ingestion). All endpoints return JSON, accept JSON, and use standard HTTP status codes.

Base URL


https://api.omniflow.example/api/v1

Test mode requests go to the same base; the API key prefix (omf_test_) is what scopes you to the test view.

Authentication

Every request needs an Authorization header:


Authorization: Bearer omf_live_xxxxxxxxxxxx

Manage keys under Settings → API Keys.

Response envelope


{
  "success": true,
  "data": { ... },
  "meta": { "request_id": "req_abc", "rate_limit": { "remaining": 59, "reset": 1730000000 } }
}

Errors use the same envelope:


{
  "success": false,
  "error": { "code": "invalid_argument", "message": "agent_id is required", "field": "agent_id" },
  "meta": { "request_id": "req_xyz" }
}

Rate limits

Header	Meaning
`X-RateLimit-Limit`	Calls allowed in the window.
`X-RateLimit-Remaining`	Calls left.
`X-RateLimit-Reset`	Unix timestamp when the window resets.
`Retry-After`	Seconds to wait (set on `429`).

Resource overview

Resource	Endpoints
Conversations	`POST/GET /conversations`, `GET /conversations/{id}/trace`
Contacts	`POST/GET/PATCH /contacts`
Companies	`POST/GET/PATCH /companies`
Tickets	`POST/GET/PATCH /tickets`, `POST /tickets/{id}/merge`
Agents	`GET /agents`, `POST /agents/{id}/test`
Scorecards	`GET /scorecards`, `GET /scorecards/{id}`
Training	`GET /training/scenarios`, `POST /training/attempts`
Webhooks	`POST/GET/DELETE /webhooks`

Conversations — POST

Create a conversation (typically for ingesting external transcripts):


curl -X POST https://api.omniflow.example/api/v1/conversations \
  -H "Authorization: Bearer $OMNIFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "call_8a2f",
    "agent": "ari@acme.com",
    "channel": "voice",
    "started_at": "2026-05-01T14:23:00Z",
    "ended_at": "2026-05-01T14:26:14Z",
    "transcript": "Agent: Thanks for calling Acme...\nCustomer: Hi, I need a refund...",
    "audio_url": "https://signed.cdn.example/call_8a2f.mp3",
    "rubric_id": "rb_default",
    "tags": ["refund", "voice"]
  }'

Response (201):


{
  "success": true,
  "data": {
    "id": "c_a1b2",
    "external_id": "call_8a2f",
    "status": "queued_for_scoring",
    "url": "https://app.omniflow.example/app/demo/conversations/c_a1b2"
  }
}

The conversation gets scored asynchronously; subscribe to scorecard.created via webhook for real-time delivery, or poll GET /conversations/{id} and read scorecard_id.

Conversations — GET trace


GET /api/v1/conversations/{id}/trace

Returns the full event tree — turns, tool calls, retrievals, transfers, errors. Used for debugging, auditing, and exporting to your data warehouse.

Contacts — upsert


curl -X POST https://api.omniflow.example/api/v1/contacts \
  -H "Authorization: Bearer $OMNIFLOW_API_KEY" \
  -d '{
    "email": "maya@acme.com",
    "first_name": "Maya",
    "phone": "+1-555-0100",
    "custom_fields": { "tier": "gold", "lifetime_value": 25000 },
    "upsert": true
  }'

upsert: true matches on email (or external_id if provided) and updates the existing record.

Tickets — create


curl -X POST https://api.omniflow.example/api/v1/tickets \
  -d '{
    "title": "Duplicate charge — order ABC123",
    "priority": "high",
    "contact_id": "ct_42",
    "linked_conversation_id": "c_a1b2",
    "tags": ["billing"]
  }'

Webhook subscriptions


curl -X POST https://api.omniflow.example/api/v1/webhooks \
  -d '{
    "url": "https://your-system.example/omniflow",
    "events": ["conversation.resolved", "ticket.created"],
    "secret": "whsec_xxxxx"
  }'

The secret is used to sign each request with HMAC-SHA256 in the X-Omniflow-Signature header. See Custom API & Webhooks.

Pagination

List endpoints use cursor-based pagination:


GET /conversations?limit=50&starting_after=c_xyz

Field	Notes
`limit`	1–100, default 25.
`starting_after`	Cursor to the last item of the previous page.
`has_more`	`true` if more pages available.

Errors

Status	Meaning
`400`	Invalid argument; see `error.field`.
`401`	Missing or invalid API key.
`403`	API key lacks the required scope.
`404`	Resource not found.
`409`	Conflict (duplicate `external_id` without `upsert`).
`429`	Rate limit hit; back off `Retry-After`.
`5xx`	Server-side; retry with backoff.

Idempotency: pass an Idempotency-Key header on POST requests; Omniflow caches the response for 24 hours so retries don’t double-create.

SDKs

Language	Package
TypeScript / Node	`@omniflow/sdk` (npm)
Python	`omniflow` (pip)
Go	`github.com/omniflow/omniflow-go`

Each SDK wraps the same API surface plus retry, idempotency, and pagination helpers.

Open in Omniflow

If you want to…	Go to
Subscribe to events	Webhooks
Wire a custom integration	Custom API & Webhooks
Debug a request	Troubleshooting