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

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.

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:

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.

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 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.
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.

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

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.

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: create a key and make your first call.
  • Errors: every code authentication can return.
  • Rate limits: how many requests each key accepts.
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