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
- The edge identifies the request. It reads the key’s prefix
(
sk_<product>_<mode>_<cell>_…) and checks its checksum. A key copied wrong is rejected here, with401 api_key_malformed, without reaching any server. - 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 ofapp.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 replies308to the same page onapp.qomni.ai/acme/agents/…. - 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.
- 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 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 replies404 api_host_movedwith 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: what each part of the key carries.
- Errors: what to do with each code.
- Idempotency and retries: how to retry a
origin_unavailablewithout creating twice.