# Qomni docs > Guides and reference for the Qomni APIs. Index: https://docs.qomni.ai/llms.txt # Qomni Agents API > The public API of Qomni Agents. One host for customers; behind it a cell runs PHP (calls, sessions) and Python (the realtime socket), which the customer never needs to know. Authentication: `Authorization: Bearer sk_agents_{live|test}_{cell}_…`. Test keys never place real calls nor bill anything. Realtime: create a session here (`createRealtimeSession`), then open its `url` and speak the messages of `asyncapi.yaml` (same folder). Demo: `createDemoSession` needs no key. It serves the public website's voice demo only (CORS for the website's origin, tight limits per IP and per day) and is not meant for integrations. Rules: contracts/STYLE.md. Source: https://docs.qomni.ai/agents-api/ · Markdown: https://docs.qomni.ai/agents-api/index.md The public API of Qomni Agents. One host for customers; behind it a cell runs PHP (calls, sessions) and Python (the realtime socket), which the customer never needs to know. Authentication: `Authorization: Bearer sk_agents_{live|test}_{cell}_…`. Test keys never place real calls nor bill anything. Realtime: create a session here (`createRealtimeSession`), then open its `url` and speak the messages of `asyncapi.yaml` (same folder). Demo: `createDemoSession` needs no key. It serves the public website's voice demo only (CORS for the website's origin, tight limits per IP and per day) and is not meant for integrations. Rules: contracts/STYLE.md. Version: 1.0.0 ## Servers - `https://api.qomni.ai/agents/v1` ## Sections - [Account](/agents-api/tags/account/) - [Calls](/agents-api/tags/calls/) - [Realtime](/agents-api/tags/realtime/) # Create call > Place an outbound call with an agent. In test mode the magic numbers decide the outcome: +15005550001 completed, +15005550002 busy, +15005550003 no-answer. Source: https://docs.qomni.ai/agents-api/calls/create/ · Markdown: https://docs.qomni.ai/agents-api/calls/create/index.md Path: Qomni Agents API › Calls `POST /calls` Place an outbound call with an agent. In test mode the magic numbers decide the outcome: +15005550001 completed, +15005550002 busy, +15005550003 no-answer. ## Authentication - `apiKey`, http, header `Authorization`, format `sk_agents_{live|test}_{cell}_{body}{checksum}` ## Request body _Required._ - `to` (`createCall.to`; string, required) — E.164, ASCII digits only. - pattern `^\+[1-9][0-9]{6,14}$` ## Example request ```json { "to": "+15005550001" } ``` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const call = await qomni.agents.createCall({ to: "+15005550001" }); console.log(call); ``` ### cURL ```bash curl --request POST \ --url https://api.qomni.ai/agents/v1/calls \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "to": "+15005550001" } ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/calls" payload = { "to": "+15005550001" } headers = { "Content-Type": "application/json", "Authorization": "Bearer " } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 201 The call. #### Example ```json { "id": "string", "to": "string", "status": "queued", "livemode": true, "cell": "string", "region": "string", "created_at": "2019-08-24T14:15:22Z" } ``` - `id` (`createCall.response.201.id`; string, required) - pattern `^call_[0-9a-z]+$` - `to` (`createCall.response.201.to`; string, required) - `status` (`createCall.response.201.status`; string, required) - one of `"queued"`, `"completed"`, `"busy"`, `"no-answer"` - `livemode` (`createCall.response.201.livemode`; boolean, required) - `created_at` (`createCall.response.201.created_at`; string, required) - format `date-time` - `cell` (`createCall.response.201.cell`; string, optional) - `region` (`createCall.response.201.region`; string, optional) ### 401 Missing or invalid credentials (`unauthenticated`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createCall.response.401.error`; object, required) - `code` (`createCall.response.401.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createCall.response.401.error.message`; string, required) — For people; may change at any time. - `request_id` (`createCall.response.401.error.request_id`; string, optional) - `fields` (`createCall.response.401.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 403 Valid credentials that may not do this (`insufficient_scope`, `api_key_wrong_product`…). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createCall.response.403.error`; object, required) - `code` (`createCall.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createCall.response.403.error.message`; string, required) — For people; may change at any time. - `request_id` (`createCall.response.403.error.request_id`; string, optional) - `fields` (`createCall.response.403.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 422 The request does not match the contract (`validation_failed`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createCall.response.422.error`; object, required) - `code` (`createCall.response.422.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createCall.response.422.error.message`; string, required) — For people; may change at any time. - `request_id` (`createCall.response.422.error.request_id`; string, optional) - `fields` (`createCall.response.422.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 Too many requests for this key (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createCall.response.429.error`; object, required) - `code` (`createCall.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createCall.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`createCall.response.429.error.request_id`; string, optional) - `fields` (`createCall.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # List calls > The latest calls in this key's mode. Live keys see live calls; test keys see test calls. Source: https://docs.qomni.ai/agents-api/calls/list/ · Markdown: https://docs.qomni.ai/agents-api/calls/list/index.md Path: Qomni Agents API › Calls `GET /calls` The latest calls in this key's mode. Live keys see live calls; test keys see test calls. ## Authentication - `apiKey`, http, header `Authorization`, format `sk_agents_{live|test}_{cell}_{body}{checksum}` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const calls = await qomni.agents.listCalls(); console.log(calls); ``` ### cURL ```bash curl --request GET \ --url https://api.qomni.ai/agents/v1/calls \ --header 'Authorization: Bearer ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/calls" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.text) ``` ## Responses ### 200 Calls, newest first. #### Example ```json { "data": [ { "id": "string", "to": "string", "status": "queued", "livemode": true, "cell": "string", "region": "string", "created_at": "2019-08-24T14:15:22Z" } ], "has_more": true, "cell": "string", "region": "string" } ``` - `data` (`listCalls.response.200.data`; array, required) - `id` (`listCalls.response.200.data.id`; string, required) - pattern `^call_[0-9a-z]+$` - `to` (`listCalls.response.200.data.to`; string, required) - `status` (`listCalls.response.200.data.status`; string, required) - one of `"queued"`, `"completed"`, `"busy"`, `"no-answer"` - `livemode` (`listCalls.response.200.data.livemode`; boolean, required) - `created_at` (`listCalls.response.200.data.created_at`; string, required) - format `date-time` - `cell` (`listCalls.response.200.data.cell`; string, optional) - `region` (`listCalls.response.200.data.region`; string, optional) - `has_more` (`listCalls.response.200.has_more`; boolean, required) - `cell` (`listCalls.response.200.cell`; string, optional) - `region` (`listCalls.response.200.region`; string, optional) ### 401 Missing or invalid credentials (`unauthenticated`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`listCalls.response.401.error`; object, required) - `code` (`listCalls.response.401.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`listCalls.response.401.error.message`; string, required) — For people; may change at any time. - `request_id` (`listCalls.response.401.error.request_id`; string, optional) - `fields` (`listCalls.response.401.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 403 Valid credentials that may not do this (`insufficient_scope`, `api_key_wrong_product`…). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`listCalls.response.403.error`; object, required) - `code` (`listCalls.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`listCalls.response.403.error.message`; string, required) — For people; may change at any time. - `request_id` (`listCalls.response.403.error.request_id`; string, optional) - `fields` (`listCalls.response.403.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 Too many requests for this key (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`listCalls.response.429.error`; object, required) - `code` (`listCalls.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`listCalls.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`listCalls.response.429.error.request_id`; string, optional) - `fields` (`listCalls.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # Create realtime session > Open a realtime voice conversation with an agent. Returns a WebSocket `url` valid for 60 seconds. The long-lived API key never travels on the socket: the session does, and its prefix (`rts_{cell}_`) takes it to the workspace's cell. Source: https://docs.qomni.ai/agents-api/create-realtime-session/ · Markdown: https://docs.qomni.ai/agents-api/create-realtime-session/index.md Path: Qomni Agents API › Realtime `POST /realtime/sessions` Open a realtime voice conversation with an agent. Returns a WebSocket `url` valid for 60 seconds. The long-lived API key never travels on the socket: the session does, and its prefix (`rts_{cell}_`) takes it to the workspace's cell. ## Authentication - `apiKey`, http, header `Authorization`, format `sk_agents_{live|test}_{cell}_{body}{checksum}` ## Request body _Optional._ - `instructions` (`createRealtimeSession.instructions`; string, optional) — What the agent should do in this conversation. - maxLength 500 ## Example request ```json { "instructions": "string" } ``` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const realtimeSession = await qomni.agents.createRealtimeSession({ instructions: "" }); console.log(realtimeSession); ``` ### cURL ```bash curl --request POST \ --url https://api.qomni.ai/agents/v1/realtime/sessions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "instructions": "string" } ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/realtime/sessions" payload = { "instructions": "string" } headers = { "Content-Type": "application/json", "Authorization": "Bearer " } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 201 The session. #### Example ```json { "id": "string", "url": "http://example.com", "client_secret": "string", "expires_at": "2019-08-24T14:15:22Z", "max_duration_seconds": 0, "livemode": true, "cell": "string" } ``` - `id` (`createRealtimeSession.response.201.id`; string, required) - pattern `^rts_[0-9a-z]+$` - `url` (`createRealtimeSession.response.201.url`; string, required) — Open within 60 s; speaks asyncapi.yaml. - format `uri` - `client_secret` (`createRealtimeSession.response.201.client_secret`; string, required) — The session, for clients that build the URL themselves. - pattern `^rts_[a-z]{2}[0-9]+_` - `expires_at` (`createRealtimeSession.response.201.expires_at`; string, required) — Connect before this instant. - format `date-time` - `max_duration_seconds` (`createRealtimeSession.response.201.max_duration_seconds`; integer, required) - `livemode` (`createRealtimeSession.response.201.livemode`; boolean, required) - `cell` (`createRealtimeSession.response.201.cell`; string, required) ### 401 Missing or invalid credentials (`unauthenticated`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createRealtimeSession.response.401.error`; object, required) - `code` (`createRealtimeSession.response.401.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createRealtimeSession.response.401.error.message`; string, required) — For people; may change at any time. - `request_id` (`createRealtimeSession.response.401.error.request_id`; string, optional) - `fields` (`createRealtimeSession.response.401.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 403 Valid credentials that may not do this (`insufficient_scope`, `api_key_wrong_product`…). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createRealtimeSession.response.403.error`; object, required) - `code` (`createRealtimeSession.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createRealtimeSession.response.403.error.message`; string, required) — For people; may change at any time. - `request_id` (`createRealtimeSession.response.403.error.request_id`; string, optional) - `fields` (`createRealtimeSession.response.403.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 422 The request does not match the contract (`validation_failed`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createRealtimeSession.response.422.error`; object, required) - `code` (`createRealtimeSession.response.422.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createRealtimeSession.response.422.error.message`; string, required) — For people; may change at any time. - `request_id` (`createRealtimeSession.response.422.error.request_id`; string, optional) - `fields` (`createRealtimeSession.response.422.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 Too many requests for this key (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createRealtimeSession.response.429.error`; object, required) - `code` (`createRealtimeSession.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createRealtimeSession.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`createRealtimeSession.response.429.error.request_id`; string, optional) - `fields` (`createRealtimeSession.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # Ask the demo to call > The website's "Llámame": the demo agent calls the visitor's phone from Qomni's demo number, in test mode, for at most `max_duration_seconds`. No key: Cloudflare Turnstile proves a person asked (`turnstile_token`), and the limits are the demo session's per IP plus one call per number a day and the same daily budget. Only numbers of Colombia, Mexico, Brazil and the US/Canada (`+57`, `+52`, `+55`, `+1`). Source: https://docs.qomni.ai/agents-api/demo-calls/create/ · Markdown: https://docs.qomni.ai/agents-api/demo-calls/create/index.md Path: Qomni Agents API › Realtime `POST /demo_calls` The website's "Llámame": the demo agent calls the visitor's phone from Qomni's demo number, in test mode, for at most `max_duration_seconds`. No key: Cloudflare Turnstile proves a person asked (`turnstile_token`), and the limits are the demo session's per IP plus one call per number a day and the same daily budget. Only numbers of Colombia, Mexico, Brazil and the US/Canada (`+57`, `+52`, `+55`, `+1`). ## Request body _Required._ - `phone` (`createDemoCall.phone`; string, required) — The number to call, E.164. - pattern `^\+(57|52|55|1)[0-9]{7,12}$` - `turnstile_token` (`createDemoCall.turnstile_token`; string, required) — The token Cloudflare Turnstile gave the website's form. - maxLength 2048 - `name` (`createDemoCall.name`; string, optional) — How the agent greets the person; optional. - maxLength 80 - `language` (`createDemoCall.language`; string, optional) - one of `"es"`, `"en"`, `"pt-br"`; default `"en"` - `agent` (`createDemoCall.agent`; string, optional) — Which demo agent answers - a receptionist, appointment booking, lead qualification, first-level support, collections or appointment reminders. - one of `"reception"`, `"scheduling"`, `"qualification"`, `"support"`, `"collections"`, `"reminders"`; default `"reception"` ## Example request ```json { "phone": "string", "name": "string", "language": "es", "agent": "reception", "turnstile_token": "string" } ``` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const demoCall = await qomni.agents.createDemoCall({ phone: "", turnstile_token: "", name: "" }); console.log(demoCall); ``` ### cURL ```bash curl --request POST \ --url https://api.qomni.ai/agents/v1/demo_calls \ --header 'Content-Type: application/json' \ --data ' { "phone": "string", "name": "string", "language": "es", "agent": "reception", "turnstile_token": "string" } ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/demo_calls" payload = { "phone": "string", "name": "string", "language": "es", "agent": "reception", "turnstile_token": "string" } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 202 The call is being placed; the phone rings within seconds. #### Example ```json { "call": "string", "max_duration_seconds": 0 } ``` - `call` (`createDemoCall.response.202.call`; string, required) - pattern `^call_[0-9a-z]+$` - `max_duration_seconds` (`createDemoCall.response.202.max_duration_seconds`; integer, required) ### 403 Turnstile did not confirm a person (`captcha_failed`), or the request came from another site (`origin_not_allowed`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoCall.response.403.error`; object, required) - `code` (`createDemoCall.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoCall.response.403.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoCall.response.403.error.request_id`; string, optional) - `fields` (`createDemoCall.response.403.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 422 The request does not match the contract (`validation_failed`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoCall.response.422.error`; object, required) - `code` (`createDemoCall.response.422.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoCall.response.422.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoCall.response.422.error.request_id`; string, optional) - `fields` (`createDemoCall.response.422.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 This address or this number has used the demo (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoCall.response.429.error`; object, required) - `code` (`createDemoCall.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoCall.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoCall.response.429.error.request_id`; string, optional) - `fields` (`createDemoCall.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 503 The demo has used today's minutes, or places no calls in this environment (`demo_unavailable`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoCall.response.503.error`; object, required) - `code` (`createDemoCall.response.503.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoCall.response.503.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoCall.response.503.error.request_id`; string, optional) - `fields` (`createDemoCall.response.503.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # Create demo session > Start a voice conversation with Qomni's demo agent from the public website, without a key. The answer is a LiveKit participant token for a new room in the demo workspace's cell, with the demo agent already dispatched into it: join `url` with `token` within 60 seconds, publish the microphone and play the agent's audio. The call is in test mode and ends by itself after `max_duration_seconds`, or after 20 seconds without the visitor speaking. Limits: 3 sessions per IP in 10 minutes and 10 in 24 hours (`rate_limited`), and a daily cap of demo minutes for everyone (`demo_unavailable`). CORS answers only the website's origin. An API key sent anyway is ignored. Source: https://docs.qomni.ai/agents-api/demo-sessions/create/ · Markdown: https://docs.qomni.ai/agents-api/demo-sessions/create/index.md Path: Qomni Agents API › Realtime `POST /demo_sessions` Start a voice conversation with Qomni's demo agent from the public website, without a key. The answer is a LiveKit participant token for a new room in the demo workspace's cell, with the demo agent already dispatched into it: join `url` with `token` within 60 seconds, publish the microphone and play the agent's audio. The call is in test mode and ends by itself after `max_duration_seconds`, or after 20 seconds without the visitor speaking. Limits: 3 sessions per IP in 10 minutes and 10 in 24 hours (`rate_limited`), and a daily cap of demo minutes for everyone (`demo_unavailable`). CORS answers only the website's origin. An API key sent anyway is ignored. ## Request body _Optional._ - `language` (`createDemoSession.language`; string, optional) — The language the demo agent speaks. - one of `"es"`, `"en"`, `"pt-br"`; default `"en"` - `agent` (`createDemoSession.agent`; string, optional) — Which demo agent answers - a receptionist, appointment booking, lead qualification, first-level support, collections or appointment reminders. - one of `"reception"`, `"scheduling"`, `"qualification"`, `"support"`, `"collections"`, `"reminders"`; default `"reception"` ## Example request ```json { "language": "es", "agent": "reception" } ``` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const demoSession = await qomni.agents.createDemoSession({ language: "es", agent: "reception" }); console.log(demoSession); ``` ### cURL ```bash curl --request POST \ --url https://api.qomni.ai/agents/v1/demo_sessions \ --header 'Content-Type: application/json' \ --data ' { "language": "es", "agent": "reception" } ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/demo_sessions" payload = { "language": "es", "agent": "reception" } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 201 The demo session. #### Example ```json { "url": "http://example.com", "token": "string", "room": "string", "expires_at": "2019-08-24T14:15:22Z", "max_duration_seconds": 0 } ``` - `url` (`createDemoSession.response.201.url`; string, required) — The cell's LiveKit (`wss://…`). - format `uri` - `token` (`createDemoSession.response.201.token`; string, required) — A LiveKit participant token for `room` only, microphone only. - `room` (`createDemoSession.response.201.room`; string, required) - pattern `^demo-[0-9a-z]+$` - `expires_at` (`createDemoSession.response.201.expires_at`; string, required) — Join before this instant. - format `date-time` - `max_duration_seconds` (`createDemoSession.response.201.max_duration_seconds`; integer, required) — The call ends by itself after this long. ### 422 The request does not match the contract (`validation_failed`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoSession.response.422.error`; object, required) - `code` (`createDemoSession.response.422.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoSession.response.422.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoSession.response.422.error.request_id`; string, optional) - `fields` (`createDemoSession.response.422.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 Too many demo sessions from this address (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoSession.response.429.error`; object, required) - `code` (`createDemoSession.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoSession.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoSession.response.429.error.request_id`; string, optional) - `fields` (`createDemoSession.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 503 The demo has used today's minutes (`demo_unavailable`), or is not offered in this environment. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`createDemoSession.response.503.error`; object, required) - `code` (`createDemoSession.response.503.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`createDemoSession.response.503.error.message`; string, required) — For people; may change at any time. - `request_id` (`createDemoSession.response.503.error.request_id`; string, optional) - `fields` (`createDemoSession.response.503.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # Get key context > The workspace, mode and cell this key works on. Useful to check a key and to see which cell answers. Source: https://docs.qomni.ai/agents-api/ping/list/ · Markdown: https://docs.qomni.ai/agents-api/ping/list/index.md Path: Qomni Agents API › Account `GET /ping` The workspace, mode and cell this key works on. Useful to check a key and to see which cell answers. ## Authentication - `apiKey`, http, header `Authorization`, format `sk_agents_{live|test}_{cell}_{body}{checksum}` ## Code samples ### TypeScript ```typescript import { Qomni } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); const context = await qomni.agents.getContext(); console.log(context); ``` ### cURL ```bash curl --request GET \ --url https://api.qomni.ai/agents/v1/ping \ --header 'Authorization: Bearer ' ``` ### Python ```python import requests url = "https://api.qomni.ai/agents/v1/ping" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.text) ``` ## Responses ### 200 The key's context. #### Example ```json { "product": "agents", "tenant": "string", "cell": "string", "region": "string", "livemode": true } ``` - `product` (`getContext.response.200.product`; string, required) - `tenant` (`getContext.response.200.tenant`; string, required) - `cell` (`getContext.response.200.cell`; string, required) - `region` (`getContext.response.200.region`; string, required) - `livemode` (`getContext.response.200.livemode`; boolean, required) ### 401 Missing or invalid credentials (`unauthenticated`). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`getContext.response.401.error`; object, required) - `code` (`getContext.response.401.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`getContext.response.401.error.message`; string, required) — For people; may change at any time. - `request_id` (`getContext.response.401.error.request_id`; string, optional) - `fields` (`getContext.response.401.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 403 Valid credentials that may not do this (`insufficient_scope`, `api_key_wrong_product`…). #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`getContext.response.403.error`; object, required) - `code` (`getContext.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`getContext.response.403.error.message`; string, required) — For people; may change at any time. - `request_id` (`getContext.response.403.error.request_id`; string, optional) - `fields` (`getContext.response.403.error.fields`; map>, optional) — Only for validation_failed, the messages per field. ### 429 Too many requests for this key (`rate_limited`); retry after `Retry-After` seconds. #### Example ```json { "error": { "code": "string", "message": "string", "request_id": "string", "fields": { "property1": [ "string" ], "property2": [ "string" ] } } } ``` - `error` (`getContext.response.429.error`; object, required) - `code` (`getContext.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return. - pattern `^[a-z][a-z0-9_]*$` - `message` (`getContext.response.429.error.message`; string, required) — For people; may change at any time. - `request_id` (`getContext.response.429.error.request_id`; string, optional) - `fields` (`getContext.response.429.error.fields`; map>, optional) — Only for validation_failed, the messages per field. # Account > Who this key is (SDK namespace `account`). Source: https://docs.qomni.ai/agents-api/tags/account/ · Markdown: https://docs.qomni.ai/agents-api/tags/account/index.md Path: Qomni Agents API Who this key is (SDK namespace `account`). ## Operations - [Get key context](/agents-api/ping/list/) # Calls > Outbound calls (SDK namespace `calls`). Source: https://docs.qomni.ai/agents-api/tags/calls/ · Markdown: https://docs.qomni.ai/agents-api/tags/calls/index.md Path: Qomni Agents API Outbound calls (SDK namespace `calls`). ## Operations - [List calls](/agents-api/calls/list/) - [Create call](/agents-api/calls/create/) # Realtime > Realtime conversation sessions (SDK namespace `realtime`). Source: https://docs.qomni.ai/agents-api/tags/realtime/ · Markdown: https://docs.qomni.ai/agents-api/tags/realtime/index.md Path: Qomni Agents API Realtime conversation sessions (SDK namespace `realtime`). ## Operations - [Create realtime session](/agents-api/create-realtime-session/) - [Create demo session](/agents-api/demo-sessions/create/) - [Ask the demo to call](/agents-api/demo-calls/create/) # Agents > Agents puts AI voice agents on calls and conversations: create calls over REST and talk to an agent in real time from your app. Source: https://docs.qomni.ai/agents/ · Markdown: https://docs.qomni.ai/agents/index.md Agents puts AI agents on calls and voice conversations. Over REST you create calls and follow their state; over a WebSocket you talk to an agent in real time from your own app, with text or audio. With the Agents API you can: - Have an agent call a customer and know how the call ended. - Open a voice conversation with an agent from a browser or an app, without exposing your key. - Test every branch of your code without dialing any number, with the magic numbers of test mode. With a test key, no call is dialed and nothing is billed. ## Get started - [Quickstart](/get-started/quickstart/) — Check your key and create your first call, in cURL, Python or TypeScript. - [Talk to an agent in real time](/agents/realtime/) — Create a session, open the socket and talk, in Python or TypeScript. - [Test mode](/concepts/test-mode/) — The magic numbers and what changes with a test key. - [BYOC: your own telephony](/concepts/byoc/) — Your carrier or your SIP trunk brings your existing numbers to your agents. ## Reference - [API reference](/agents-api/) — Calls and realtime sessions: every endpoint, field and error. - [Realtime WebSocket](/agents/websocket/) — Every message you send and receive over the /realtime channel. # API reference > Every endpoint, field and error of the Agents API, generated from its contract. Source: https://docs.qomni.ai/agents/api/ · Markdown: https://docs.qomni.ai/agents/api/index.md # Talk to an agent in realtime > Open a voice conversation with a Qomni agent from your app over WebSocket, without exposing your key, in Python or TypeScript. Source: https://docs.qomni.ai/agents/realtime/ · Markdown: https://docs.qomni.ai/agents/realtime/index.md A realtime conversation has two steps: your server creates a session over REST with its key, and your client opens a WebSocket with that session's `url`. **The key never travels over the socket.** In this guide one program does both parts, so you can try it in one go. In production, the server creates the session and the browser or the app only receives the `url`. ```mermaid sequenceDiagram participant C as Client participant S as Your server participant A as Agents API S->>A: POST /agents/v1/realtime/sessions (secret key) A-->>S: { url }, valid for 60 s S-->>C: the url C->>A: opens the WebSocket A-->>C: session.started C->>A: input_text.send A-->>C: response.text.delta … A-->>C: response.done C->>A: session.end A-->>C: session.ended (billed minutes) ``` ## Before you begin You need: - An Agents test key (`sk_agents_test_…`), stored in the `QOMNI_KEY` environment variable. - Python 3.10 or later, or Node.js 22 or later (it ships with `fetch` and `WebSocket`). 1. ### Install what you need In Python we use `requests` for the REST call and `websockets` for the socket. In Node.js, `tsx` runs TypeScript without compiling it. ```bash export QOMNI_KEY="sk_agents_test_…" pip install requests websockets ``` ```bash export QOMNI_KEY="sk_agents_test_…" npm install --save-dev tsx ``` 2. ### Create a session To open a conversation, request a session with your key. `instructions` is optional and tells the agent what to do in this conversation: ```bash curl https://api.qomni.ai/agents/v1/realtime/sessions \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Responde en una frase" }' ``` The response carries the socket's `url`. Open it within **60 seconds**: ```json title="201 Created" { "id": "rts_01k8x3d5n2p7q4r6s8t0v1w3y5", "url": "wss://api.qomni.ai/agents/v1/realtime?session=rts_co1_…", "client_secret": "rts_co1_…", "expires_at": "2026-10-21T15:05:05Z", "max_duration_seconds": 900, "livemode": false, "cell": "co1" } ``` 3. ### Open the socket and talk The program creates the session, waits for `session.started`, sends a question, prints the reply as it arrives and hangs up. Save it as `realtime.py` or `realtime.mts`: ```python import asyncio import json import os import requests import websockets QUESTION = { "type": "input_text.send", "text": "¿Hacen domicilios al centro?", } HANG_UP = {"type": "session.end"} def create_session() -> str: key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/realtime/sessions", headers={"Authorization": f"Bearer {key}"}, json={"instructions": "Responde en una frase"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") return response.json()["url"] async def converse(url: str) -> None: async with websockets.connect(url) as socket: async for raw in socket: message = json.loads(raw) match message["type"]: case "session.started": await socket.send(json.dumps(QUESTION)) case "response.text.delta": print(message["delta"], end="", flush=True) case "response.done": print() await socket.send(json.dumps(HANG_UP)) case "session.ended": print(message) case "error": raise SystemExit(message["error"]["code"]) asyncio.run(converse(create_session())) ``` ```typescript const url = "https://api.qomni.ai/agents/v1/realtime/sessions"; const response = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ instructions: "Responde en una frase" }), }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } const session = await response.json(); const socket = new WebSocket(session.url); const send = (message: object) => socket.send(JSON.stringify(message)); socket.onmessage = ({ data }) => { const message = JSON.parse(data); switch (message.type) { case "session.started": send({ type: "input_text.send", text: "¿Hacen domicilios al centro?", }); break; case "response.text.delta": process.stdout.write(message.delta); break; case "response.done": console.log(); send({ type: "session.end" }); break; case "session.ended": console.log(message); break; case "error": throw new Error(message.error.code); } }; ``` Run it: ```bash python realtime.py ``` ```bash npx tsx realtime.mts ``` ## You should see The agent's reply appears word by word, followed by the `session.ended` message. In test mode, `billed_minutes` is always `0`: ```text Sí, llevamos pedidos al centro de lunes a sábado. {'type': 'session.ended', 'reason': 'client_ended', 'billed_minutes': 0, 'usage_record_id': None} ``` If you see `api_key_malformed` instead, the key was copied wrong: export `QOMNI_KEY` again. If you see `realtime_session_invalid`, more than 60 seconds passed between creating the session and opening the socket. ## Hanging up The program hangs up on its own when it receives `response.done`: it sends `session.end`, and the server replies `session.ended` with the billed minutes and closes the socket. If you do not hang up, the session ends by itself after `max_duration_seconds` (900 seconds) with `reason: max_duration`. ## Next steps You now have a complete conversation with an agent. To put it in your app, split the two parts: your server creates the session and hands the `url` to the client. - [Realtime WebSocket](/agents/websocket/): every message on the channel, including audio. - [API keys and authentication](/concepts/authentication/): why the key must never reach the browser. - [Test mode](/concepts/test-mode/): what changes with a test key. # Realtime WebSocket > The messages of the /realtime channel, generated from contracts/public/agents/v1/asyncapi.yaml. Source: https://docs.qomni.ai/agents/websocket/ · Markdown: https://docs.qomni.ai/agents/websocket/index.md The socket opens at `/realtime?session=rts_…` with the session that `POST /agents/v1/realtime/sessions` returns; the secret key never travels over it. Every message is a JSON object with `type`. ## The client sends Turns (text or audio), instruction changes and the end of the conversation. ### `session.update` Change the agent's instructions mid-conversation. ```json { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "session.update" }, "instructions": { "type": "string", "maxLength": 500 } } } ``` ### `input_text.send` A complete user turn, as text. ```json { "type": "object", "required": [ "type", "text" ], "additionalProperties": false, "properties": { "type": { "const": "input_text.send" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } } } ``` ### `input_audio.append` A chunk of the user's audio. ```json { "type": "object", "required": [ "type", "audio" ], "additionalProperties": false, "properties": { "type": { "const": "input_audio.append" }, "audio": { "type": "string", "contentEncoding": "base64", "description": "PCM 16-bit little-endian, 16 kHz, mono." } } } ``` ### `input_audio.commit` The user stopped talking; the agent answers what it heard. ```json { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "input_audio.commit" } } } ``` ### `session.end` Hang up. ```json { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "const": "session.end" } } } ``` ## The server sends The session start, the agent's answer in deltas, running usage, errors and the end. ### `session.started` ```json { "type": "object", "required": [ "type", "session" ], "properties": { "type": { "const": "session.started" }, "session": { "type": "object", "required": [ "id", "workspace", "cell", "livemode", "input_audio_format", "max_duration_seconds" ], "properties": { "id": { "type": "string" }, "workspace": { "type": "string" }, "cell": { "type": "string" }, "livemode": { "type": "boolean" }, "input_audio_format": { "type": "string", "const": "pcm16_16khz_mono" }, "max_duration_seconds": { "type": "integer" }, "served_by": { "type": "string", "description": "The service and language that answered (agents-runtime/python)." } } } } } ``` ### `response.text.delta` The next piece of the agent's answer. ```json { "type": "object", "required": [ "type", "response_id", "delta" ], "properties": { "type": { "const": "response.text.delta" }, "response_id": { "type": "string" }, "delta": { "type": "string" } } } ``` ### `response.done` ```json { "type": "object", "required": [ "type", "response_id", "text" ], "properties": { "type": { "const": "response.done" }, "response_id": { "type": "string" }, "text": { "type": "string" } } } ``` ### `usage.updated` Running totals, after every turn. ```json { "type": "object", "required": [ "type", "elapsed_seconds", "audio_seconds", "turns" ], "properties": { "type": { "const": "usage.updated" }, "elapsed_seconds": { "type": "number" }, "audio_seconds": { "type": "number" }, "turns": { "type": "integer" } } } ``` ### `session.ended` ```json { "type": "object", "required": [ "type", "reason", "billed_minutes" ], "properties": { "type": { "const": "session.ended" }, "reason": { "type": "string", "enum": [ "client_ended", "max_duration", "client_disconnected" ] }, "billed_minutes": { "type": "integer", "description": "0 in test mode." }, "usage_record_id": { "type": [ "string", "null" ], "description": "The billing record (contracts/internal/proto/qomni/billing/v1), when billed." } } } ``` ### `error` ```json { "type": "object", "required": [ "type", "error" ], "properties": { "type": { "const": "error" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "invalid_message, unknown_message_type, session_expired…" }, "message": { "type": "string" } } } } } ``` # Blog > Qomni engineering notes: how the platform is built, what we decided and why, told by the people who build it. Source: https://docs.qomni.ai/blog/ · Markdown: https://docs.qomni.ai/blog/index.md How the platform is built, decision by decision: why data lives in one cell per country, what an API key carries, how an AI agent answers a call. Written by the team that builds it. # Why each workspace's data lives in one cell per country > Qomni keeps a workspace's data in its own country and puts a single entry point in front. What problem it solves and what it cost. Source: https://docs.qomni.ai/blog/una-celda-por-pais/ · Markdown: https://docs.qomni.ai/blog/una-celda-por-pais/index.md A call recording in Colombia, its transcript in Brazil and an agent's record in the United States have different legal rules. All three live in Qomni. The design question was where to store them, and the answer defines almost everything else: one **cell** per country. ## The problem A single database for the whole world is the simplest option to operate. It forces you to pick one country for every customer's data and to explain that choice to each of them. With voice recordings and customer conversations, that explanation does not always convince. The usual alternative is one region per customer, chosen at sign-up. It puts the decision in the hands of whoever has the least context. And it makes it show up everywhere: in the API URL, in the client's configuration, in every SDK. ## What we did Every workspace is born in a cell (`us1`, `co1` or `br1`): a complete copy of the platform in one region. In front of all the cells there is a single entry point, the **edge**, a Cloudflare Worker that receives every request and takes it to the right cell. ```mermaid flowchart LR C[Your server] -- "sk_agents_live_co1_…" --> E[Edge] E -- "10 s token" --> CO[(Cell co1)] E -.-> US[(Cell us1)] E -.-> BR[(Cell br1)] ``` The cell never appears in a URL. It goes inside the API key (`sk_agents_live_co1_…`), and the edge reads it from there without looking anything up. For the web app, it comes from the workspace you signed in to. Your code is the same for a customer in Bogotá and for one in São Paulo. ## What it cost - **An origin cannot trust anyone but the edge.** That is why the edge signs every request with an Ed25519 token. It is valid for 10 seconds, serves a single request and is bound to the host, the cell and the client's IP. An origin rejects anything that does not carry that token, so nobody can skip the edge by calling a cell directly. - **A key is only valid in its cell.** Using it in another one responds `421 wrong_cell`. In practice it does not happen, because the key's cell is the one of the workspace that created it, but the rule exists so that a configuration mistake never crosses data between countries. - **Data does not move.** A workspace stays in its cell. Moving one would mean moving customer recordings from one country to another, and we would rather not have that tool than have it and use it badly. ## What we gained Complying with each country's rules is a property of the architecture, not a process. A request travels less. And a customer never has to choose a region or remember it. If you want to see the full journey of a request, it is in [The edge and the cells](/concepts/edge/). # What a Qomni API key carries inside > The sk_product_mode_cell key format and what each part saves the edge, the client and support. Source: https://docs.qomni.ai/blog/una-clave-por-producto/ · Markdown: https://docs.qomni.ai/blog/una-clave-por-producto/index.md An API key looks like a random string, but Qomni's tells a story: `sk_agents_live_co1_8fK2…Qa91Zx`. Each part is there for a concrete reason, and those reasons are the subject of this note. ## The product, in the key Each Qomni product has its API, its usage and its invoice. A key is valid for a single product. With an Agents key you can call `api.qomni.ai/agents/v1` and nothing else; on another API it fails with `401 api_key_wrong_product`. It is an attack-surface decision. A system that creates calls gets an Agents key and, if that key leaks, the attacker gets into neither the web app nor the account. And revoking one key does not touch the others. ## The mode, in the key `live` or `test` is not an account setting: the key decides it. A test key works on separate data, dials no number and bills nothing. The code is the same; one environment variable changes. So what you test is exactly what will run in production. ## The cell, to look nothing up `co1` says where the workspace's data lives. The edge reads that prefix and sends the request to the right cell without searching any database. It is the reason the API URL never carries a region. ## The checksum, to fail early The last six characters are a CRC32 of the rest, in base62. A badly copied key is rejected at the edge, with `401 api_key_malformed`, before reaching any server. Support recognizes that error without looking at anything else. ## What is not in the key Qomni stores only the SHA-256 hash of each key. That is why the full key is shown once, when it is created, and afterwards only its prefix and its last four characters are visible. A lost key is not recovered: you create another and revoke the previous one. ```mermaid flowchart LR K["sk_agents_live_co1_8fK2…Qa91Zx"] --> P[sk: secret] K --> R[agents: product] K --> M[live: mode] K --> C[co1: cell] K --> S[30 characters: secret] K --> X[6 characters: checksum] ``` ## And the limits Each key has its own budget: 120 requests per minute. Requests rejected with `401` are counted separately, per IP address, so that a misconfigured client does not exhaust the budget of the valid keys on the same network. The full anatomy is in [API keys and authentication](/concepts/authentication/). # Changelog > What changed in the API and in this documentation, by date: what is new, what changed and what was fixed in each release. Source: https://docs.qomni.ai/changelog/ · Markdown: https://docs.qomni.ai/changelog/index.md ## 2026-11-18 · Beta: the website, the waitlist and this documentation are public {#2026-11-18-beta-public} Qomni Agents enters private beta. From today `qomni.ai` and this documentation are public, and you can join the waitlist. The API and the app are not open yet. ### New - [qomni.ai](https://qomni.ai/) with the Agents waitlist: you leave your e-mail and we write to you once, when it opens. - This documentation at `docs.qomni.ai`, in Spanish, English and Portuguese. - [Beta status](/get-started/beta/): what is done, what is left and how it opens, step by step until the first customer. ### Changed - Agents shows as "Coming soon" across the portal and every guide says the API does not respond yet. The examples show how it will work. ## 2026-10-25 · The API on a single host {#2026-10-25-one-api-host} The Qomni API now lives at `api.qomni.ai`, with the product and the version in the path: `https://api.qomni.ai/agents/v1`. The previous host (`agents-api.qomni.ai`) no longer serves requests: it responds `404 api_host_moved` with the new base URL, without redirecting. ### Changed - API base URL: `https://api.qomni.ai/agents/v1`, previously `https://agents-api.qomni.ai/v1`. Change your client's base URL; the paths, keys and responses do not change. See [Welcome](/get-started/). - Realtime: create the session with `POST https://api.qomni.ai/agents/v1/realtime/sessions`; its `url` is `wss://api.qomni.ai/agents/v1/realtime?session=…`. See [Talk to an agent in real time](/agents/realtime/). - TypeScript SDK: `baseUrl` is now the host (by default `https://api.qomni.ai`) and each product adds its `/{product}/v1`. See [Use the TypeScript SDK](/get-started/sdks/). - New errors: `404 api_host_moved` on the old host and `404 unknown_api` when the path does not start with an API. See [Errors](/concepts/errors/). ## 2026-10-23 · Tutorials, and a changelog per product with RSS {#2026-10-23-tutorials-changelog} A [tutorials](/tutorials/) section with end-to-end solutions, and this page with a product filter, a page per entry and RSS. ### New - [Tutorials](/tutorials/): end-to-end guides with the time they take, filterable by product, and "Start here" on the home page. - Product filter above the list (`?product=agents` shares it) and [changelog RSS](/changelog/rss.xml) in each language. - Each entry has its own URL (`/es/changelog/2026-10-23-blog-subscriptions/`), with the previous and the next one at the foot; the home page and the product menu link there. ### Changed - The timeline carries the date in a column on the left, the title as a link and the product as a tag in its color; entries run from newest to oldest. - The home page groups products by category and the hero prompt is a button with the marks of the AI agents. A "Ready for your AI agent" band gathers `llms.txt`, `llms-full.txt` and the Markdown of each page. ## 2026-10-22 · Agents: BYOC, connect your own telephony {#2026-10-22-byoc} ![Your usual carrier and line reach your voice agents](/changelog/2026-10-22-byoc.svg) Bring your carrier or your SIP trunk and your usual numbers reach your voice agents, without porting anything and without changing provider. ### New - [BYOC: your own telephony](/concepts/byoc/): the two ways to bring it (SIP trunk and forwarded line), which agent answers each number and how to call out through your carrier. - An announcement in the portal presents BYOC with its link; dismiss it once and it does not come back. ## 2026-10-23 · Blog subscriptions by email {#2026-10-23-blog-subscriptions} The blog emails you about each new article: leave your address at the foot of any article or of the list, confirm from the email and you are done. ### New - Subscription form on the [blog](/blog/) and at the end of each article, with email confirmation (double opt-in) and unsubscribe from any message. - The API behind it, `api.qomni.ai/newsletter/v1` (`POST /subscriptions`), never says whether an address is already subscribed and accepts five sign-ups per hour from the same IP address. - The blog in three languages, also by RSS: `/es/blog/rss.xml`, `/blog/rss.xml` and `/pt-br/blog/rss.xml`. ## 2026-10-22 · Agents: TypeScript SDK {#2026-10-22-typescript-sdk} `@qomni/sdk` calls the Agents API with one method per operation, the contract's types and errors with a code; the reference shows its calls. ### New - [Use the TypeScript SDK](/get-started/sdks/): `new Qomni({ apiKey })` and `qomni.agents.createCall(…)`, with `idempotencyKey` as an option and `QomniError` (`status`, `code`, `message`, `requestId`, `fields`). - The TypeScript example of each operation in the [Agents reference](/agents-api/) uses the SDK; cURL and Python stay as they were. - The SDK is generated from the contract with `bin/contracts generate`; it is not on npm yet and installs from the repository. - Announcements in the portal: a card presents the latest new feature, with a link and, when there is one, a video; dismiss it once and it does not come back. ## 2026-10-21 · Complete examples, diagrams and blog {#2026-10-21-examples-diagrams-blog} The portal gets a new face: the examples in the guides are whole programs with their output, processes are explained with diagrams, there is an engineering blog and this log details each release. ### New - [Blog](/blog/): engineering notes on how the platform is built, starting with [cells per country](/blog/una-celda-por-pais/) and [the anatomy of an API key](/blog/una-clave-por-producto/). - Process diagrams in [The edge and the cells](/concepts/edge/), [Idempotency and retries](/concepts/idempotency/) and [Talk to an agent](/agents/realtime/). They open at full size with one click. - Product menu with a preview: hover over a product to see its host, its first call and its guides; on the right, the latest announcements with an image. - "On this page" menu under the title on small screens, with the section you are reading marked. - The sidebar can be hidden from its button; the choice is remembered. ### Changed - Neutral theme, light and dark: whites and grays, with the brand color only in the logo and in what is selected (tab, menu row, indicator). - Code examples show the languages as tabs in the block's header, with each one's icon, a single copy button and line numbers; choosing Python in one block chooses it in all of them. - The guides follow Cloudflare's style guide: each page type (overview, quickstart, concept, task, reference) has the same shape, with "Before you begin", "You should see" and "Next step" in the tasks. - API reference: each operation has a short title ("Create call") and its explanation apart, and the endpoint groups have a name. The example's language selector is a menu with each language's icon. The sidebar starts with Overview and the product's Reference, like the one in its guides. - This log: each entry carries its date in a lane, the product as a tag and the lists of what is new, changed and fixed. - More compact tables and pagination in cards with the title of the previous and the next page. ### Fixed - The Colombian flag in the language menu was drawn wrong. - The sidebar's width changed from one page to another. - A click on an image in the guides did not open the viewer. ## 2026-10-21 · Documentation in English and Portuguese {#2026-10-21-english-portuguese} ![The guides in Spanish, English and Portuguese](/changelog/2026-10-21-languages.svg) The guides are now also in English and in Portuguese. Switch language from the header menu: it takes you to the same page. ### New - English at the site root (`docs.qomni.ai/concepts/errors/`) and Portuguese under `/pt-br/`, translated from the Spanish guides and reviewed. - Language menu in the header, with each language's flag. - Each page declares its versions in the other languages (`hreflang`), so that a search engine shows the reader's. ### Changed - Spanish moves to `/es/`; each previous URL redirects to its new page. - The API reference stays in English and is the same for the three languages; its menu and its links are in the page's language. ## 2026-10-21 · New home page and product directory {#2026-10-21-home-directory} The home page shows the product with its first call, the latest changes and what is common to the whole API. ### New - [Directory](/directory/) with the products by category, with a text filter. - Each page can be opened in Claude or in ChatGPT, copied as Markdown or viewed in Markdown from its actions menu. ### Changed - The Qomni logo, a custom typeface for headings (replaced the next day by the system's) and transitions between pages: the active tab and row slide to the next one. - Product menu next to the logo, with the product's icon and outcome. ## 2026-10-18 · New portal {#2026-10-18-new-portal} The documentation moved to its own portal, generated from `contracts/`. ### New - The Agents section with its REST reference. - The [Agents WebSocket reference](/agents/websocket/), generated from its AsyncAPI. - The guides in Spanish, with the same menu and the same search as the reference. ## 2026-10-03 · New developer documentation {#2026-10-03-developer-docs} One page per product, examples in cURL, Python and TypeScript in the guides and this changelog. # Concepts > What holds across the whole Qomni Agents API: keys, the edge, errors, test mode, retries, limits and your own telephony. Source: https://docs.qomni.ai/concepts/ · Markdown: https://docs.qomni.ai/concepts/index.md The whole Qomni API shares these rules: if you know them for one endpoint, you know them for all. - [API keys and authentication](/concepts/authentication/) — One secret key per product and mode, sent as a bearer token. - [The edge and the cells](/concepts/edge/) — What happens to your request between your server and the API. - [Errors](/concepts/errors/) — One shape across the whole API. - [Test mode](/concepts/test-mode/) — The real API, without real consequences. - [Idempotency and retries](/concepts/idempotency/) — Retry without creating twice. - [Rate limits](/concepts/rate-limits/) — How many requests per minute the API accepts. - [BYOC: your own telephony](/concepts/byoc/) — Your carrier or your SIP trunk; your existing numbers reach your agents. # API keys and authentication > What a Qomni API key is, what parts it has and why each key works for a single product, a single mode and a single cell. Source: https://docs.qomni.ai/concepts/authentication/ · Markdown: https://docs.qomni.ai/concepts/authentication/index.md To call the Qomni API you need an **API key**: a secret string that identifies your workspace, the product you call and the mode (test or live). You send it in every request, in the `Authorization` header, as a bearer token: ```http Authorization: Bearer sk_agents_live_co1_8fK2…Qa91Zx ``` A key works for a single product. With an Agents key you can call `https://api.qomni.ai/agents/v1` and nothing else. If the API receives a key from another product, the request fails with `401 api_key_wrong_product`. > **Caution** > > Keys are for your server. **Never put them in a browser or in a mobile app**: > anyone could read them. To talk to an agent from a browser, use a > [realtime session](#sesiones-en-tiempo-real). ## Why one key per product Each Qomni product has its own API, its own usage and its own invoice. One key per product gives you three things: - **Least access.** A system that creates calls gets an Agents key and nothing else. If that key leaks, the attacker gets into neither your account nor the web app. - **Revocation without collateral damage.** You revoke one key and the others keep working. - **Routing without lookups.** The key carries the cell where your data lives. The edge reads the prefix and sends the request to the right place without looking anything up in a database. [The edge and cells](/concepts/edge/) explains it. ## Anatomy of a key
sk{"_"}agents{"_"}live{"_"}co1{"_8fK2…"}Qa91Zx
| Part | What it means | |---|---| | `sk` | A secret key. | | `agents` | The product it works for. Today, `agents`. | | `live` / `test` | Live mode or [test mode](/concepts/test-mode/). | | `co1` | The cell where the workspace's data lives. You do not need to read it. | | 30 characters | The secret itself. | | 6 final characters | A checksum. A badly copied key is rejected before it reaches any server (`401 api_key_malformed`). | ## Modes: test and live The mode is not an account setting: the key you use decides it. A `sk_agents_test_…` key works on test data and never dials a number. A `sk_agents_live_…` key works on real data and is billed. Your code is the same in both cases; you change the key and nothing else. The details are in [Test mode](/concepts/test-mode/). ## How it is stored and shown Qomni stores only the hash of each key, never the text. That is why the full key is shown **only once**, when you create it. After that you only see its prefix and its last four characters. If you lose a key, there is no way to recover it: create another one and revoke the old one. Revocation is immediate: the next request with that key fails with `401 api_key_invalid`. ## Realtime sessions {#sesiones-en-tiempo-real} A WebSocket opened from a browser cannot send headers, so it cannot carry your key. That is what the session is for: your server creates it with its key over REST, receives a `url` valid for 60 seconds and hands it to the client. The client opens the socket with that `url`. The key never leaves your server. You do it step by step in [Talk to an agent in realtime](/agents/realtime/). ## Limits - A key is not a user: it does not sign you in to the web app or the identity API. - A key does not work in another product (`401 api_key_wrong_product`) or in another cell (`421 wrong_cell`). - A key from a workspace without the product enabled responds `403 product_not_active`, even if the key is valid. - A key belongs to one mode: to go to production you create a `live` key, you do not convert the test one. ## See also - [Quickstart](/get-started/quickstart/): create a key and make your first call. - [Errors](/concepts/errors/): every code authentication can return. - [Rate limits](/concepts/rate-limits/): how many requests each key accepts. # BYOC: your own telephony > How your carrier or your SIP trunk brings your existing numbers to Qomni Agents voice agents, without porting anything or switching providers. Source: https://docs.qomni.ai/concepts/byoc/ · Markdown: https://docs.qomni.ai/concepts/byoc/index.md **BYOC** (*Bring Your Own Carrier*) means your telephony stays yours and Qomni only provides the agent. You got your numbers from your carrier and your customers know them: you do not port them, publish a new one or switch providers. Your carrier or your SIP trunk carries each call to your workspace's SIP network, and there the agent you chose for that number answers. Each workspace has its own SIP network: a domain (`acme.sip.qomni.ai`), an inbound trunk with a username and a password only you know, and one room per call in your workspace's region. A call that does not come in through your trunk never reaches your agents. ## Why the telephony is yours A voice agent is useful where people already call you. Providers that sell their own numbers force you to port or announce a new one, and to pay for their minutes. Qomni does the opposite: the transport (SIP and RTP) stays with your carrier, at its rates, and Qomni provides the agent, the room where it talks and the call record. It is also safer this way. Because the trunk has its own credentials per workspace, a forward or a forged header can only choose among **your** agents, never send the call to another workspace. ## Two ways to bring it They can be combined. ```mermaid flowchart LR subgraph T[Your telephony] O[Your carrier] L[Your existing line] end O -- "SIP trunk" --> K[LiveKit SIP in your cell] L -- "forwarding + Diversion" --> K K --> A[Voice agent] ``` | Way | When | What you do | |---|---|---| | **SIP trunk** | You have a carrier or a SIP trunk and want your numbers to come in directly | In **Telephony** you enable inbound calls. Qomni gives you the SIP domain, a username and a password; your carrier points your numbers there | | **Forwarded line** | You have an existing number (landline or mobile) and do not want to touch anything else | You ask your carrier to forward that line to a trunk number and declare the line in Qomni. We recognize the number your customer dialed (`Diversion` or `History-Info`) and that line's agent answers | A PBX you already have (Asterisk, FreePBX, Issabel, 3CX…) comes in through the first: its outbound trunk points to your Qomni SIP network, as it would with one more carrier. ## Which agent answers The number decides. If your customer dialed your existing line and the carrier forwarded it, we use the number they dialed, not the trunk's. | Case | Who answers | |---|---| | Number with an assigned agent | That agent | | Unassigned number and a single active voice agent | That agent | | No possible agent | A short message; the call goes unanswered | ## Calling out Also through your telephony. An outbound trunk with your carrier's address and credentials lets the agent call with your numbers: that is what `POST /agents/v1/calls` uses in live mode. ## Limits - Qomni does not sell numbers or port them: today every call comes in through your telephony. - The agent transfers only to the destinations you configure for it; it does not dial another number even if asked. - Only a voice agent can answer a trunk; a chat agent does not answer calls. ## See also - [Agents](/agents/): the product and its guides. - [Quickstart](/get-started/quickstart/): create your first call in test mode. - [API reference](/agents-api/): `calls` and `realtime/sessions`. # The edge and cells > Where your workspace's data lives, what the edge does with each request and why your code never chooses a region. Source: https://docs.qomni.ai/concepts/edge/ · Markdown: https://docs.qomni.ai/concepts/edge/index.md Each workspace's data lives in a **cell**: a complete copy of the platform in one region (`us1` in the United States, `co1` in Colombia, `br1` in Brazil). In front of all the cells there is a single entry point, the **edge**, which receives each request and carries it to the right cell. For you this means one thing: the API lives on a single host, `api.qomni.ai`, with the product and the version in the path (`https://api.qomni.ai/agents/v1`), and the URL never carries a region. Your code is the same for a customer in Bogotá and for one in São Paulo. The web app also has a single host, `app.qomni.ai`: the portal and each product's page inside each workspace, at `app.qomni.ai/{workspace}/{producto}` (for example `app.qomni.ai/acme/agents`). The old addresses of each product (`agents.qomni.ai/acme`…) redirect there. ## Why there are cells Call recordings and transcripts have different legal rules in each country. Storing a workspace's data in its own country makes complying with them simpler and the path of each request shorter. The alternative, a single database for the whole world, would force choosing one country for everyone. Qomni chose not to push that decision into your code. That is why the cell goes inside the API key (`sk_agents_live_co1_…`) and the edge reads it from there. There is no region parameter, no host per country, nothing you can misconfigure. ## The journey of a request ```mermaid flowchart LR S[Your server] -- "sk_agents_live_co1_…" --> E[Edge] E -- "10 s token" --> C1[(Cell co1
api)] E -.-> C2[(Cell us1)] E -.-> C3[(Cell br1)] ``` 1. **The edge identifies the request.** It reads the key's prefix (`sk____…`) and checks its checksum. A key copied wrong is rejected here, with `401 api_key_malformed`, without reaching any server. 2. **It finds the cell.** With an API key, the cell is in the key. In the web app, a product page (`app.qomni.ai/{workspace}/{producto}/…`) goes to the cell of the workspace in its path; the rest of `app.qomni.ai` (your workspaces, settings, sign-in) does not live in any cell. An old product address (`agents.qomni.ai/acme/…`) reaches no cell: the edge replies `308` to the same page on `app.qomni.ai/acme/agents/…`. 3. **It signs an edge token.** It is valid for 10 seconds, serves a single request and is bound to the public host, the cell and your IP address. 4. **It forwards the request** to the service in that cell that serves the path, with the path as is. Which service that is cannot be seen from outside. The origin only accepts requests that carry the token: nobody can skip the edge by calling an origin directly. The response carries the `X-Request-Id` header. Store it in your logs: it is what support uses to find your request. ## Edge errors They have the same [shape](/concepts/errors/) as API errors. | Code | When | |---|---| | `api_key_missing`, `api_key_malformed` | The `Authorization` header is missing, or the key does not have the expected shape or checksum. | | `realtime_session_invalid` | The WebSocket session does not exist or has expired. It is valid for 60 seconds. | | `origin_unavailable` | The cell did not respond. Nothing happened: retry with backoff. | | `unknown_api` | `404`: the first segment of the path on `api.qomni.ai` does not name any API (`/payroll/v1/…`). | | `api_host_moved` | `404`: the host is the old API address (`agents-api.qomni.ai`). Use `https://api.qomni.ai/agents/v1`. | | `not_found`, `method_not_allowed` | The path or the method does not exist in that API. | | `product_host_moved` | `410`: a method other than `GET` or `HEAD` on the old address of a product (`agents.qomni.ai`). Send the request to `app.qomni.ai/{workspace}/{producto}`. | | `host_moved` | `404`: the host is the old address of a product, which no longer serves pages. | ## Limits - Your code never chooses the cell. There is no parameter, host or header for that. - The old API address (`agents-api.qomni.ai`) does not redirect: it replies `404 api_host_moved` with the new base URL. - A key is only valid in its cell. Using it in another replies `421 wrong_cell`. In practice it does not happen: the key's cell is that of the workspace that created it. - Data does not move between cells. A workspace is born in a cell and stays there. - The edge neither stores nor reads your data: it only routes and signs. ## See also - [API keys and authentication](/concepts/authentication/): what each part of the key carries. - [Errors](/concepts/errors/): what to do with each code. - [Idempotency and retries](/concepts/idempotency/): how to retry a `origin_unavailable` without creating twice. # Errors > The shape of every Qomni API error, each field it carries and what to do with each code and HTTP status. Source: https://docs.qomni.ai/concepts/errors/ · Markdown: https://docs.qomni.ai/concepts/errors/index.md Every error of the Qomni API has the same shape, defined once in `contracts/shared/v1/components.yaml#/components/schemas/Error`. Decide by `code`, show `message` and store `request_id`. ## Codes | Status | `code` | What to do | |---|---|---| | `401` | `api_key_missing` | The `Authorization` header is missing. Send `Authorization: Bearer `. | | `401` | `api_key_malformed` | The key does not have the form `sk_…` or its checksum does not match. Copy it again. | | `401` | `api_key_invalid` | The key does not exist or was revoked. Create another one. | | `401` | `api_key_wrong_product` | The key belongs to another product. Use an Agents key. | | `403` | `product_not_active` | The workspace does not have Agents enabled. Enable it in **Settings**. | | `404` | `not_found` | The route or the resource does not exist. | | `404` | `host_moved` | The host is a product's old address (`agents.qomni.ai`), which no longer serves pages. Use `https://app.qomni.ai/{workspace}/{producto}`. | | `404` | `api_host_moved` | The host is the API's old address (`agents-api.qomni.ai`). It does not redirect: `message` carries the new base URL, `https://api.qomni.ai/agents/v1`. Change your client's base URL. | | `404` | `unknown_api` | The first segment of the path on `api.qomni.ai` does not name any API. Start the path with the product and the version (`/agents/v1/…`). | | `405` | `method_not_allowed` | The route exists, but not with that method. | | `410` | `product_host_moved` | You sent a `POST`, `PUT`, `PATCH` or `DELETE` to a product's old address (`agents.qomni.ai`). Those addresses only redirect a `GET` or `HEAD` to `app.qomni.ai/{workspace}/{producto}`; send the request there. The API does not go through those addresses: it lives at `https://api.qomni.ai/agents/v1`. | | `421` | `wrong_cell` | The key belongs to another cell. It does not happen with a key created by the workspace. | | `422` | `validation_failed` | A field is missing or invalid. Fix the fields in `fields`. Unknown fields are rejected too. | | `429` | `rate_limited` | You exceeded the limit. Wait the seconds in `Retry-After` and retry. See [Rate limits](/concepts/rate-limits/). | | `503` | `origin_unavailable` | The cell did not respond. Nothing was done: retry with backoff. See [Idempotency](/concepts/idempotency/). | Each operation in the reference also lists the codes specific to that operation, for example `demo_unavailable` when opening a demo session. ## Shape ```json { "error": { "code": "api_key_wrong_product", "message": "This key is for another product.", "request_id": "req_01m40n2ansfhj861etnav19mbp" } } ``` | Field | Type | Description | |---|---|---| | `code` | string, required | Stable. It is the value your code decides on. | | `message` | string, required | For people. It can change at any time: never compare against it. | | `request_id` | string, required | Identifies the request. Include it when you write to support. | | `fields` | object | Only in `validation_failed`: the messages for each field, by name. | On the Agents WebSocket, an error is a message of type `error` with the same `{ code, message }` object inside. ## In your code Read `code` and store `request_id`. For example, when you create a call without a destination the API responds `422` with the detail of each field in `fields`: ```python if not response.ok: error = response.json()["error"] if error["code"] == "validation_failed": print(error["fields"]) raise SystemExit(f"{error['code']} ({error['request_id']})") ``` ```typescript if (!response.ok) { const { error } = await response.json(); if (error.code === "validation_failed") console.log(error.fields); throw new Error(`${error.code} (${error.request_id})`); } ``` ```json title="422 Unprocessable Content" { "error": { "code": "validation_failed", "message": "The to field is required.", "request_id": "req_52abfa8dd5144eee89f62f0c653310e5", "fields": { "to": ["The to field is required."] } } } ``` # Idempotency and retries > What an idempotent request is, when it is safe to retry a call to Qomni and how to use the Idempotency-Key header. Source: https://docs.qomni.ai/concepts/idempotency/ · Markdown: https://docs.qomni.ai/concepts/idempotency/index.md A request is **idempotent** when repeating it produces the same result as making it once. Listing your calls is idempotent: do it ten times and the list does not change. Creating a call is not: create it twice and the agent dials the same customer twice. Networks fail, so your code has to retry. The problem is retrying a request that creates something without creating it twice. ## Why the problem exists The dangerous case is not when the request fails. It is when you do not know whether it failed: ```mermaid sequenceDiagram participant S as Your server participant Q as Agents API S->>Q: POST /agents/v1/calls Q->>Q: creates call_01… and the agent dials Q--xS: the response is lost S->>Q: retry: POST /agents/v1/calls Q->>Q: creates call_02… and the agent dials again Q-->>S: 201 call_02… ``` 1. Your server sends `POST /agents/v1/calls`. 2. Qomni creates the call and the agent dials the customer. 3. The response is lost along the way (the connection drops, your timeout expires). 4. Your code sees a network error and retries. 5. Qomni creates a second call and the customer receives two. From your side, steps 2 and 3 are invisible: a network failure before the response looks the same as a network failure before the request arrived. No client can tell them apart on its own. ## How it is solved The solution is that you name each operation. You send an `Idempotency-Key` header with a value you choose, and repeat that same value on every retry of the same operation. That way the API can recognize the retry and return the first result instead of creating another call. ```bash curl https://api.qomni.ai/agents/v1/calls \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1042-reminder" \ -d '{ "to": "+15005550001" }' ``` ```python import os import requests key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/calls", headers={ "Authorization": f"Bearer {key}", "Idempotency-Key": "order-1042-reminder", }, json={"to": "+15005550001"}, timeout=10, ) ``` ```typescript const response = await fetch("https://api.qomni.ai/agents/v1/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "order-1042-reminder", }, body: JSON.stringify({ to: "+15005550001" }), }); ``` A good key comes from your own data: the id of the order being reminded about, the id of the appointment being confirmed, the customer id plus the date. A random key generated on each retry is useless, because each retry would carry a new key. > **Current status** > > The API accepts the `Idempotency-Key` header as the contract says, but > deduplication is not active yet: today a retry creates a second > resource. In the meantime, retry only when you know the request did not > arrive (`503 origin_unavailable`, or a connection error before sending the > body) and store the `id` of each response so you do not repeat an operation that > already has a result. ## When to retry | What you got | Retry | Why | |---|---|---| | `503 origin_unavailable` | Yes, with backoff | The cell did not receive the request. Nothing happened. | | `429 rate_limited` | Yes, after `Retry-After` seconds | The request was not processed. | | Connection error before sending the body | Yes | The request did not arrive. | | Timeout while waiting for the response | Only with `Idempotency-Key` | It may have arrived and been processed. | | `4xx` other than `429` | No | The request is wrong. Retrying it as is will fail the same way. | Use **exponential backoff**: wait 1 second, then 2, then 4, with a maximum of five attempts. Retrying without waiting only makes a cell that is already saturated worse. ## Limits - `GET` requests are already idempotent. They do not need the header. - The key identifies an operation, not a resource. Two different orders carry two different keys even if they call the same number. - The key does not change what the request does. If you retry with the same key and a different body, the body that counts is the first one. ## See also - [Errors](/concepts/errors/): what each code means before deciding to retry. - [Rate limits](/concepts/rate-limits/): the `Retry-After` of a `429`. - [The edge and cells](/concepts/edge/): where a `origin_unavailable` comes from. # Rate limits > Each limit of the Qomni Agents API (requests per minute, session duration), its scope and what happens when you exceed it. Source: https://docs.qomni.ai/concepts/rate-limits/ · Markdown: https://docs.qomni.ai/concepts/rate-limits/index.md Limits protect each cell from a burst, yours or another customer's. They are per key: two keys from the same workspace do not share a quota. When you exceed a request limit, the API responds `429 rate_limited` with a `Retry-After` header that says how many seconds to wait. | Limit | Value | Scope | When exceeded | |---|---|---|---| | API requests | 120 per minute | Per key | `429 rate_limited`, `Retry-After` | | Requests rejected with `401` | 60 per minute | Per IP address | `429 rate_limited`, `Retry-After` | | Time to open a realtime session | 60 seconds from creation | Per session | `realtime_session_invalid` on connect | | Duration of a realtime session | 900 seconds | Per session | The server hangs up with `session.ended`, `reason: max_duration` | ## API requests Each key has its own budget of **120 requests per minute**. Two keys behind the same IP do not share a quota. A request rejected with a `4xx` counts too. ## Requests rejected with `401` Requests without a key, with a malformed key or with a key from another product are counted separately, **per IP address**, with a limit of 60 per minute. That way a misconfigured client cannot exhaust the budget of the valid keys coming from the same network. ## Realtime sessions `POST /agents/v1/realtime/sessions` returns a `url` that you must open within **60 seconds**. A conversation lasts at most **900 seconds**: after that time, the server sends `session.ended` with `reason: max_duration` and closes the socket. # Test mode > What changes when you use an Agents test key, what does not change, and how to test each branch of your integration without dialing any number. Source: https://docs.qomni.ai/concepts/test-mode/ · Markdown: https://docs.qomni.ai/concepts/test-mode/index.md The Qomni API has two modes: **live** and **test**. The key you use decides the mode: `sk_agents_live_…` or `sk_agents_test_…`. There is no separate environment, no other host and no setting to turn on. It is the same API, with the same validation and the same errors, on separate data and without consequences. With a test key: - no number is dialed and nothing is sent to anyone; - nothing is billed; - test data lives apart from live data. A live key never sees it, and the other way around. ## Why it works this way A separate test environment, with another host and another database, forces you to maintain two configurations and to trust that both behave the same. That is almost never true. Qomni uses the same code and the same host for both modes, and separates only the data. So what you test is exactly what will run in production. Going live is changing an environment variable. ## What changes with a test key | Resource | With a test key | |---|---| | Calls | No number is dialed. The [magic numbers](#números-mágicos) decide the call's outcome. | | Realtime sessions | They work the same as in live mode and end with `billed_minutes: 0`. | ## Magic numbers {#números-mágicos} To test each branch of your code, in test mode a call to these numbers has a fixed outcome: | Number | Outcome | |---|---| | `+15005550001` | `completed` | | `+15005550002` | `busy` | | `+15005550003` | `no-answer` | Any other number in test mode ends `completed`. ## Limits - Test mode is not a copy of your live data. It starts empty and only holds what you create with test keys. - The rate limits are the same: 120 requests per minute per key. - A test key does not become a live key. When you go to production, create a `live` key and revoke the test keys you no longer use. - Validation is identical. A `422` in test will be a `422` in live. ## See also - [API keys and authentication](/concepts/authentication/): the key decides the mode. - [Quickstart](/get-started/quickstart/): your first call, in test mode. - [Rate limits](/concepts/rate-limits/): the same in both modes. # Events > The CloudEvents envelope every Qomni event shares. Source: https://docs.qomni.ai/events/ · Markdown: https://docs.qomni.ai/events/index.md Every event is a [CloudEvent 1.0](https://cloudevents.io): the same envelope and, inside `data`, what is specific to each event. `id` is the idempotency key (it comes from the work, not from chance) and `subject` is the workspace, so a consumer can drop duplicates and process in order per workspace. Names follow `ai.qomni....v`. ## Envelope CloudEvents 1.0 as every qomni event uses it (STYLE.md, events). Each event schema is this envelope plus its `type` and its `data`. `id` is the idempotency key, derived from the work; `subject` is the workspace slug, so brokers partition by workspace; `time` is when it happened. | Field | Type | Detail | | --- | --- | --- | | `specversion`
Required | string | `"1.0"` | | `id`
Required | string | ≤ 200 | | `source`
Required | string | Who publishes it, e.g. /cells/co1/agents | | `type`
Required | string | | | `time`
Required | string | `date-time` | | `datacontenttype`
Required | string | `"application/json"` | | `subject`
Required | string | The workspace slug. | | `livemode`
Optional | boolean | CloudEvents extension: false for test-mode work. | | `traceparent`
Optional | string | CloudEvents distributed-tracing extension. | | `data`
Required | object | | ## Shared objects Objects several events carry inside `data`. ### `actor` Who or what acted: an agent, a member, an API key (its ID, never the key) or the system. | Field | Type | Detail | | --- | --- | --- | | `type`
Required | string | `agent`, `member`, `api_key`, `system` | | `id`
Required | string | | | `on_behalf_of`
Optional | string | The member an API key or an approved agent action acts for. | ### `subject` | Field | Type | Detail | | --- | --- | --- | | `type`
Required | string | `agent`, `conversation`, `call`, `phone_number` | | `id`
Required | string | | # Welcome > What Qomni Agents is, what its API does and which rules every endpoint shares, so you can choose where to start. Source: https://docs.qomni.ai/get-started/ · Markdown: https://docs.qomni.ai/get-started/index.md Qomni is Agents: AI agents that answer the phone, call your customers and talk in real time from your app. It has a web app to manage them and an API to put them in your code. The whole API follows the same rules: the same keys, the same errors and the same test mode. If you learn one endpoint, you know how to use them all. ## What the API does | Resource | What you do with it | Where | |---|---|---| | Calls | An agent calls a number and tells you how it ended | `POST /calls`, `GET /calls` | | Realtime sessions | Your app opens a voice or text conversation with an agent, without exposing your key | `POST /realtime/sessions` and a WebSocket | | Key context | Check a key and see which cell your workspace lives in | `GET /ping` | The API lives on a single host, `api.qomni.ai`: the path starts with the product and then the version, `https://api.qomni.ai/agents/v1`. It speaks JSON and is versioned in the path. Within a version, fields are only added, never removed: your client must ignore the fields it does not know. ## What holds for every endpoint - **One key per mode.** `sk_agents_test_…` to test, `sk_agents_live_…` for production. See [API keys and authentication](/concepts/authentication/). - **A single host.** Your code does not pick a region: the key carries the cell and the edge routes. See [The edge and the cells](/concepts/edge/). - **The same error shape.** `code` for your code, `message` for people, `request_id` for support. See [Errors](/concepts/errors/). - **Test mode without consequences.** The same API, without dialing or billing anything. See [Test mode](/concepts/test-mode/). ## Where to start - [Quickstart](/get-started/quickstart/) — Check a key and have an agent call a number, in five minutes. - [Talk to an agent in real time](/agents/realtime/) — Create a session, open the socket and talk from your app. - [Concepts](/concepts/) — The rules that hold for the whole API. - [API reference](/agents-api/) — Every endpoint, field and error, generated from the contract. # Beta status > Where the Qomni Agents beta stands, what you can use today and what is left before the first customer takes real calls. Source: https://docs.qomni.ai/get-started/beta/ · Markdown: https://docs.qomni.ai/get-started/beta/index.md Qomni Agents is in private beta. Today you can read this documentation and join the waitlist; the API and the app are not open yet. This page says what is done and what is left, and it is updated with every step. | Step | Status | Date | |---|---|---| | Public website and waitlist | ● Done | 2026-11-18 | | Public documentation | ● Done | 2026-11-18 | | Platform in production: account, workspace and API keys | ◐ In progress | — | | First voice cell: telephony and agents taking calls | ○ Pending | — | | Closed beta with the first customers from the waitlist | ○ Pending | — | | First customer with real calls in production | ○ Pending | — | | Open registration | ○ Pending | — | ## What you can do today - Join the [waitlist](https://qomni.ai/agents/#lista): we write to you once, when it opens. - Read the guides and the [API reference](/agents-api/) to prepare your integration. - Follow every step in the [changelog](/changelog/), also by [RSS](/changelog/rss.xml). ## What does not work yet - `api.qomni.ai` does not respond: the examples in the guides show how the API will work, but you cannot run them yet. - There is no registration or sign-in: `id.qomni.ai` and `app.qomni.ai` open with the platform. - No API keys are issued, test or live. The API described here may change before it opens. Every change is recorded in the [changelog](/changelog/). ## How the beta opens The beta opens by invitation, in the order of the waitlist. The first customer comes in with direct support: we connect their telephony, set up their agent and review the first calls together. Once that customer takes real calls, the next group is invited. We do not publish dates we cannot keep: a step gets its date the day it is done. # Quickstart > Check your Agents key and have an agent call a number in five minutes, from the terminal, Python or TypeScript. Source: https://docs.qomni.ai/get-started/quickstart/ · Markdown: https://docs.qomni.ai/get-started/quickstart/index.md By the end of this guide you will have checked your key and created a call with the Agents API. Everything runs in **test mode**: no number is dialed and nothing is billed. ## Before you begin You need: - A Qomni account (14-day free trial, no card). - A terminal with `curl`, or Python 3.9 or later, or Node.js 18 or later. 1. ### Create a test key Sign up at [qomni.ai](https://qomni.ai). In **Settings → API keys** of your workspace, create a test key: it starts with `sk_agents_test_`. Store it in an environment variable of your shell: ```bash export QOMNI_KEY="sk_agents_test_…" ``` The examples on this page read it from `QOMNI_KEY`. Do not write it in your code or push it to a repository. 2. ### Install what you need With cURL you need nothing else. In Python we use `requests`; Node.js already ships `fetch`, and `tsx` runs TypeScript without compiling it. ```bash pip install requests ``` ```bash npm install --save-dev tsx ``` 3. ### Check the key Ask the API for your key's context. Save the code as `ping.py` or `ping.mts`, or paste the cURL command into your terminal: ```bash curl https://api.qomni.ai/agents/v1/ping \ -H "Authorization: Bearer $QOMNI_KEY" ``` ```python import os import requests key = os.environ["QOMNI_KEY"] response = requests.get( "https://api.qomni.ai/agents/v1/ping", headers={"Authorization": f"Bearer {key}"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") print(response.json()) ``` ```typescript const response = await fetch("https://api.qomni.ai/agents/v1/ping", { headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}` }, }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } console.log(await response.json()); ``` Run it: ```bash python ping.py ``` ```bash npx tsx ping.mts ``` A `200` carries your workspace and `livemode: false`, because the key is a test key. The response may carry more fields: ignore the ones you do not know. ```json title="200 OK" { "product": "agents", "tenant": "acme", "cell": "co1", "region": "co", "livemode": false } ``` A `401` means the key is missing or not valid: the error's `code` field tells you which of the two. See [Errors](/concepts/errors/). 4. ### Create a call Ask an agent to call a number. In test mode, `+15005550001` is a [magic number](/concepts/test-mode/) that always ends `completed`. Save the code as `create_call.py` or `create_call.mts` and run it as in the previous step: ```bash curl https://api.qomni.ai/agents/v1/calls \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15005550001" }' ``` ```python import os import requests key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/calls", headers={"Authorization": f"Bearer {key}"}, json={"to": "+15005550001"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") call = response.json() print(call["id"], call["status"]) ``` ```typescript const url = "https://api.qomni.ai/agents/v1/calls"; const response = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to: "+15005550001" }), }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } const call = await response.json(); console.log(call.id, call.status); ``` The API responds `201` with the call: ```json title="201 Created" { "id": "call_01k8x2m4v7q9r3t5w8y1z0a2b4", "to": "+15005550001", "status": "completed", "livemode": false, "cell": "co1", "region": "co", "created_at": "2026-10-21T15:04:05+00:00" } ``` ## You should see The call exists, with status `completed`, and no phone rang: that is how [test mode](/concepts/test-mode/) works. You have just made the two calls every integration with Agents makes: check the key and create a call. `GET /calls` returns them, most recent first. If in step 3 you saw `401`, the `code` field says why: `api_key_missing` if the header is missing, `api_key_malformed` if the key was copied wrong, `api_key_invalid` if it was revoked. ## Next step Swap the test key for a real one (`sk_agents_live_…`) and the same code makes real calls. Before that, get the agent talking to your app: - [Talk to an agent in real time](/agents/realtime/) — Create a session and talk to the agent over WebSocket, without exposing your key. - [Agents reference](/agents-api/): every endpoint, field and error. - [Idempotency and retries](/concepts/idempotency/): retry without creating two calls. # Use the TypeScript SDK > Call the Agents API from TypeScript or JavaScript with @qomni/sdk: one method per operation, types from the contract and errors with a code. Source: https://docs.qomni.ai/get-started/sdks/ · Markdown: https://docs.qomni.ai/get-started/sdks/index.md `@qomni/sdk` wraps every operation of the [reference](/agents-api/) in a method with the contract's types: `qomni.agents.createCall`, `qomni.agents.listCalls`, `qomni.agents.createRealtimeSession` and the rest. It is generated from the contract, so a method always asks for what the operation asks for. ## Before you begin - Bun, or Node.js 22.18 or later (both run TypeScript without compiling). - An Agents test key (`sk_agents_test_…`) in the `QOMNI_KEY` variable, as in the [quickstart](/get-started/quickstart/). - The package is not on npm yet: install it from the `sdks/typescript/` folder of the Qomni repository. 1. ### Install the package ```shell pnpm add ../qomni/sdks/typescript ``` 2. ### Create the client and make a call The key decides the product and the mode: an Agents key works in `qomni.agents`. Save the code as `call.mts`. ```ts title="call.mts" import { Qomni, QomniError } from "@qomni/sdk"; const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! }); try { const call = await qomni.agents.createCall( { to: "+15005550001" }, { idempotencyKey: "order-1001" }, ); console.log(call.id, call.status); } catch (error) { if (error instanceof QomniError) { console.error(error.status, error.code, error.message); } else { throw error; } } ``` 3. ### Run it ```shell bun run call.mts ``` Node.js 22.18 or later runs the same file as is: ```shell node call.mts ``` ## You should see ```text title="Salida" call_01hv4k8s2m9q7w3e5r6t8y0u1i completed ``` The SDK sent `POST https://api.qomni.ai/agents/v1/calls` with your key in `Authorization`, the body as JSON and `Idempotency-Key: order-1001`. In test mode no phone rang: `+15005550001` is a magic number that ends `completed`. If the key is not valid, the API responds `401` and the SDK throws a `QomniError` with the error's `code`, for example `api_key_malformed`. ## Next steps - Each method is named after its operation in the [Agents reference](/agents-api/): path parameters, then the body, then the query, then the options (`idempotencyKey`, `signal`, `headers`). The TypeScript example of each operation already uses the SDK. - [Talk to an agent in real time](/agents/realtime/): `createRealtimeSession` opens the conversation. - [Errors](/concepts/errors/): the codes a `QomniError` can carry. - [Idempotency](/concepts/idempotency/): when to send `idempotencyKey`. # Tutorials > End-to-end solutions with the Qomni APIs, step by step and with the time they take: you end up with something that works. Source: https://docs.qomni.ai/tutorials/ · Markdown: https://docs.qomni.ai/tutorials/index.md