HeyRik API

Build AI voice agents programmatically — create an agent, give it knowledge, assign a phone number, place calls, and read back the transcript, recording and outcome.

Base URL

https://server.heyrik.com/api/v1

Authentication

Authorization: Bearer cg_live_xxxxxxxxxxxx
# …or
X-API-Key: cg_live_xxxxxxxxxxxx

Create a key in the dashboard under API. A key is scoped to the account that made it — it only ever sees that account's agents, numbers and calls; anything else returns 404. Keep keys server-side: whoever holds one can place calls that spend your credits.

Quickstart — agent to live call

# 1. Create the agent
curl -X POST https://server.heyrik.com/api/v1/agents \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "language": "en-IN",
    "greeting": "Hi, thanks for calling Acme — how can I help?",
    "system_prompt": "You are a friendly support agent for Acme."
  }'

# 2. Point one of your numbers at it (handles INBOUND from now on)
curl https://server.heyrik.com/api/v1/phone-numbers -H "Authorization: Bearer $HEYRIK_API_KEY"

curl -X PATCH https://server.heyrik.com/api/v1/phone-numbers/sip_45723ca5 \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agency_id": "agc_9f2a1c30" }'

# 3. Place an OUTBOUND call
curl -X POST https://server.heyrik.com/api/v1/calls/dispatch \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "sip_45723ca5",
    "to": "+919876543210",
    "agent_id": "agc_9f2a1c30"
  }'

# 4. Read the result once it's over
curl https://server.heyrik.com/api/v1/calls/call_1dd990f7 -H "Authorization: Bearer $HEYRIK_API_KEY"

Ids come from GET /phone-numbers and GET /agents.

Agents

An agent is the AI that speaks on a call. You define its behaviour as an ordered Conversation Flow (config.prompt_sections) — the same structured sections the dashboard builder uses — plus a voice, languages and call settings. Create one, then point a phone number at it or dial out with it.

Knowledge base

Give an agent documents to answer from — a price list, a policy page, an FAQ. It quotes these instead of improvising.

Phone numbers

List your numbers and choose which agent answers each one. Buying a number needs completed KYC and happens in the dashboard.

Calls

Dial out with an agent, then read back the transcript, recording, outcome and what it cost.

Custom APIs (integrations)

Register your own endpoint as a tool the agent can call mid-conversation — look up an order, check availability, create a ticket.

Voices

Browse the voice library, list your cloned voices, preview one, or clone a new voice from a short recording. A voice's id goes into voice_settings.voice_id on any agent.

Campaigns (bulk calling)

Call a list of leads with one agent. Seed from a CSV or push leads in live, then start, pause and export results.

Analytics

The numbers a dashboard is built around — calls made and connected, answer rate, talk time — overall, per agent, and as a daily series.

Agent settings

What the builder UI fills its pickers from — the supported languages and performance tiers. Read these instead of hardcoding lists, so your dashboard never drifts from ours.

CRM — leads & folders

A lead pipeline you can drive entirely from your own app: import contacts, move them through stages, and dial them.

Chat widgets

Embed a text agent on your own website. Create a widget, drop its snippet in, and those conversations arrive alongside your calls.

Account & balance

Who the key belongs to, and how many credits are left — check this before starting a large campaign.

Errors

Every failure returns { "error": "code", "hint": "…" } — the hint is written to be safe to show your own users.

400invalid_requestA required field is missing or malformed. The `hint` says which.
401api_key_requiredNo key sent, or it's revoked. Create one in the dashboard → API.
402insufficient_creditsNot enough credits to start the call. `need` gives the minimum.
403kyc_requiredIdentity verification isn't complete — finish it in the dashboard.
404not_foundNo such id ON YOUR ACCOUNT. Keys never see another account's data.
409name_already_usedThat name is taken — custom API names are unique per account.
429rate_limitedToo many requests for this key. Back off and retry.
500server_errorOur side. Safe to retry; contact support if it persists.

Dashboard only

Not on the API, because each involves money or regulated identity checks that need a person:

Buying a phone number — requires completed KYC.
Identity verification (PAN, Aadhaar, GST, CIN).
Plans, credit top-ups and payment methods.