Skip to content
Qomni

Agents

Create an agent, give it a voice and put it to work: REST for the calls and a WebSocket to talk to it in real time from your app.

Base URL
https://api.qomni.ai/agents/v1
Key
sk_agents_test_…
curl https://api.qomni.ai/agents/v1/calls \
  -H "Authorization: Bearer sk_agents_test_…"

What's new

Errors

The shape of every Qomni API error, each field it carries and what to do with each code and HTTP status.

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 <key>.
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.
503 origin_unavailable The cell did not respond. Nothing was done: retry with backoff. See Idempotency.

Each operation in the reference also lists the codes specific to that operation, for example demo_unavailable when opening a demo session.

Shape

{
  "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:

422 Unprocessable Contentjson
{
  "error": {
    "code": "validation_failed",
    "message": "The to field is required.",
    "request_id": "req_52abfa8dd5144eee89f62f0c653310e5",
    "fields": {
      "to": ["The to field is required."]
    }
  }
}
Site navigation

New

2 of 7 steps doneNext: the platform in production

Qomni is in private beta

The API and the app are not open yet. See what is done, what is left and how it opens, step by step until the first customer.

Type to search…

↑↓ move↵ openEsc to close