HeyRik public API
Find every public resource, method, parameter, request, response, and operational note without leaving the reference context.
Base URL and authentication
Send one account-scoped key with every request. Keep it on your server because it can place paid calls and access account data.
https://server.heyrik.com/api/v1Authorization: Bearer $HEYRIK_API_KEYNew to HeyRik? Follow the complete Academy course before using the endpoint catalogue.
Agents
6 operationsAn 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
4 operationsGive an agent documents to answer from — a price list, a policy page, an FAQ. It quotes these instead of improvising.
Phone numbers
5 operationsList your numbers and choose which agent answers each one. Buying a number needs completed KYC and happens in the dashboard.
Calls
4 operationsDial out with an agent, then read back the transcript, recording, outcome and what it cost.
Custom APIs (integrations)
4 operationsRegister your own endpoint as a tool the agent can call mid-conversation — look up an order, check availability, create a ticket.
Voices
3 operationsBrowse 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)
13 operationsCall a list of leads with one agent. Seed from a CSV/XLSX or push leads in live, then start, pause and export results. A campaign is continuous: leads that arrive after it has finished are dialled automatically. Every lead field is matched to the agent's input variables by meaning (AI), so a column called "Decision Maker" fills {{prospect_name}} without renaming. Each finished call can be POSTed to your webhook_url — see the Connect your backend guide.
Analytics
3 operationsThe numbers a dashboard is built around — calls made and connected, answer rate, talk time — overall, per agent, and as a daily series.
Agent settings
7 operationsWhat 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
13 operationsA lead pipeline you can drive entirely from your own app: import contacts, move them through stages, and dial them.
Chat (text agents)
8 operationsTalk to an agent over TEXT — no phone call, no speech. Use a one-shot completion for a quick answer, or a stateful session that remembers the whole conversation. Billed per message (much cheaper than a call), so it's ideal for testing an agent's brain or powering a chatbot in your own product. Same agents as your calls — an agent id from POST /agents works here directly.
Chat widgets
5 operationsEmbed a text agent on your own website. Create a widget, drop its snippet in, and those conversations arrive alongside your calls.
Account & balance
3 operationsWho the key belongs to, and how many credits are left — check this before starting a large campaign.
Errors
Failures return { "error": "code", "hint": "…" }. Use the status and hint to decide whether to correct, retry, or escalate.
invalid_requestA required field is missing or malformed. The `hint` says which.
api_key_requiredNo key sent, or it's revoked. Create one in the dashboard → API.
insufficient_creditsNot enough credits to start the call. `need` gives the minimum.
kyc_requiredIdentity verification isn't complete — finish it in the dashboard.
not_foundNo such id ON YOUR ACCOUNT. Keys never see another account's data.
name_already_usedThat name is taken — custom API names are unique per account.
rate_limitedToo many requests for this key. Back off and retry.
server_errorOur side. Safe to retry; contact support if it persists.
Dashboard-only actions
Money and regulated identity workflows stay in the HeyRik dashboard.