Getting started

Create a key and place your first call.

The oyehello API is a REST API over HTTPS. All requests go to:

https://api.oyehello.ai

Responses are JSON. The public API is versioned under /v1 - the contract is stable and changes only additively.

1. Create an API key

In the console, under Account → API keys (owner or admin), create a key, choose its scopes, and copy it immediately - it’s shown only once. Keys look like:

ohk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Store it in a secret manager or environment variable. See Authentication for how the key works - including that your workspace is implicit in the key, so you never pass a tenant id.

2. Send the key

Every request carries the key as a Bearer token:

Authorization: Bearer ohk_live_…

A quick check - list your agents (needs the agents:read scope):

curl https://api.oyehello.ai/v1/agents \
  -H "Authorization: Bearer ohk_live_…"
{ "data": [ { "id": "agt_…", "name": "Sales", "voice": "simran", "language": "hi", "status": "active" } ] }

Successful responses wrap the payload in { "data": … } (the one exception is placing a call).

3. Place your first call

With calls:write, a published agent, and an owned number, place a call:

curl -X POST https://api.oyehello.ai/v1/calls \
  -H "Authorization: Bearer ohk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "agt_…", "toNumber": "+919812345678", "externalRef": "your-id" }'
{ "placed": true, "interactionId": "call_…", "providerCallId": "prov_…" }

The call runs the agent’s full compliance pipeline before it dials. Fetch the result later with GET /v1/calls/{interactionId}.

Before live calls work

Placing a call requires a KYB-verified workspace, a funded wallet, and at least one owned number - otherwise you’ll get a 403, 402, or 400. See Calls for the full gate list.

Where next