---
title: "Quickstart"
description: "Check your Agents key and have an agent call a number in five minutes, from the terminal, Python or TypeScript."
version: "en"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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.

Source: https://docs.qomni.ai/get-started/quickstart/index.mdx
