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.
-
Create a test key
Sign up at 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: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. -
Install what you need
With cURL you need nothing else. In Python we use
requests; Node.js already shipsfetch, andtsxruns TypeScript without compiling it.pip install requestsnpm install --save-dev tsx -
Check the key
Ask the API for your key’s context. Save the code as
ping.pyorping.mts, or paste the cURL command into your terminal:curl https://api.qomni.ai/agents/v1/ping \ -H "Authorization: Bearer $QOMNI_KEY"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())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:
python ping.pynpx tsx ping.mtsA
200carries your workspace andlivemode: false, because the key is a test key. The response may carry more fields: ignore the ones you do not know.200 OKjson { "product": "agents", "tenant": "acme", "cell": "co1", "region": "co", "livemode": false }A
401means the key is missing or not valid: the error’scodefield tells you which of the two. See Errors. -
Create a call
Ask an agent to call a number. In test mode,
+15005550001is a magic number that always endscompleted. Save the code ascreate_call.pyorcreate_call.mtsand run it as in the previous step:curl https://api.qomni.ai/agents/v1/calls \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15005550001" }'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"])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
201with the call:201 Createdjson { "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 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:
- Agents reference: every endpoint, field and error.
- Idempotency and retries: retry without creating two calls.