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

Idempotency and retries

What an idempotent request is, when it is safe to retry a call to Qomni and how to use the Idempotency-Key header.

A request is idempotent when repeating it produces the same result as making it once. Listing your calls is idempotent: do it ten times and the list does not change. Creating a call is not: create it twice and the agent dials the same customer twice.

Networks fail, so your code has to retry. The problem is retrying a request that creates something without creating it twice.

Why the problem exists

The dangerous case is not when the request fails. It is when you do not know whether it failed:

POST /agents/v1/callscreates call_01… and the agent dialsthe response is lostretry: POST /agents/v1/callscreates call_02… and the agent dials again201 call_02…Your serverAgents APIYour serverAgents API
  1. Your server sends POST /agents/v1/calls.
  2. Qomni creates the call and the agent dials the customer.
  3. The response is lost along the way (the connection drops, your timeout expires).
  4. Your code sees a network error and retries.
  5. Qomni creates a second call and the customer receives two.

From your side, steps 2 and 3 are invisible: a network failure before the response looks the same as a network failure before the request arrived. No client can tell them apart on its own.

How it is solved

The solution is that you name each operation. You send an Idempotency-Key header with a value you choose, and repeat that same value on every retry of the same operation. That way the API can recognize the retry and return the first result instead of creating another call.

A good key comes from your own data: the id of the order being reminded about, the id of the appointment being confirmed, the customer id plus the date. A random key generated on each retry is useless, because each retry would carry a new key.

When to retry

What you got Retry Why
503 origin_unavailable Yes, with backoff The cell did not receive the request. Nothing happened.
429 rate_limited Yes, after Retry-After seconds The request was not processed.
Connection error before sending the body Yes The request did not arrive.
Timeout while waiting for the response Only with Idempotency-Key It may have arrived and been processed.
4xx other than 429 No The request is wrong. Retrying it as is will fail the same way.

Use exponential backoff: wait 1 second, then 2, then 4, with a maximum of five attempts. Retrying without waiting only makes a cell that is already saturated worse.

Limits

  • GET requests are already idempotent. They do not need the header.
  • The key identifies an operation, not a resource. Two different orders carry two different keys even if they call the same number.
  • The key does not change what the request does. If you retry with the same key and a different body, the body that counts is the first one.

See also

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