API Reference

The Vocily REST API lets your backend do the whole loop over HTTP: build and configure an agent, publish a version and put it live, place outbound calls, and read back calls, chats and what the agent remembered - with the transcript, recording, cost and analysis for each. Pair it with webhooks to get call events pushed to you as they happen instead of polling.

Some things stay in the dashboard, by design. Creating an API key, buying or connecting a phone number, setting an agent’s webhook URL, connecting WhatsApp and its templates, building HTTP tools, and running batch campaigns. Each one either spends money, signs an agreement, or hands us a third party’s credentials.

The API is server-side only - authenticate with a secret API key. Never ship a key in a browser, mobile app, or anything a customer can view.

Base URL

https://api.vocily.ai

Every endpoint below is relative to this host, e.g. POST https://api.vocily.ai/v1/calls.

Authentication

Send your key as a Bearer token:

Authorization: Bearer vk_your_key_here

curl https://api.vocily.ai/v1/agents \
  -H "Authorization: Bearer vk_your_key_here"

import requests

r = requests.get(
    "https://api.vocily.ai/v1/agents",
    headers={"Authorization": "Bearer vk_your_key_here"},
)
r.raise_for_status()
print(r.json())

const res = await fetch("https://api.vocily.ai/v1/agents", {
  headers: { Authorization: "Bearer vk_your_key_here" },
});
console.log(await res.json());

Create and manage keys in the dashboard under Developers → API Keys. The full secret is shown once, at creation - store it somewhere safe.

What a key can do

There is nothing to configure. Every key reaches the whole public API for the one workspace it belongs to: place calls, read calls and chats with their transcripts and recordings, list agents and phone numbers, and manage knowledge bases. A key cannot reach anything outside that surface. Account settings, billing, team members and key management itself are dashboard-only and answer 403 to any key, so a leaked key cannot change your account or mint another key. To cut off a key, revoke it in the dashboard; it stops working immediately.

Keys are workspace-scoped: a key issued in one workspace can never see another workspace’s calls or agents, whatever the request says. There is no header for choosing one - the key decides. X-Vocily-Workspace and X-Vocily-Org belong to the dashboard’s own session; sent with a key they are ignored when they agree with it and refused with 403 when they do not.

The endpoints

Place a call

POST /v1/calls

List calls

GET /v1/calls

Get a call

GET /v1/calls/{id}

Get a recording

GET /v1/calls/{id}/recording

List chats

GET /v1/chats - widget + web text conversations

List agents

GET /v1/agents

List phone numbers

GET /v1/numbers

Knowledge bases

Full CRUD + attach to an agent

Webhooks

Get call events pushed to you

Voice and text are separate

A call is a voice conversation - a phone leg, or browser audio from your embedded widget. A chat is a text conversation. They are separate resources because they carry different data and are billed differently:

	`/v1/calls`	`/v1/chats`
Channels	phone (inbound + outbound), widget voice, dashboard test calls	widget chat, dashboard chat tests
Has	`from_number`, `to_number`, `duration_seconds`, `recording_url`, `transfer`	`turn_count`
Billed	per minute (`rate_per_min`)	per assistant reply (`rate_per_reply`)
Both have	`transcript`, `custom_analysis`, `metadata`, `variables`, `cost`

Two fields tell you where a conversation came from:

direction on a call - inbound, outbound, or web for a call that happened in a browser rather than on a phone. Filter with ?direction=, which takes the same three values. A web call carries no numbers.
origin on both - widget, dashboard, api, batch, inbound or demo. This is how you separate real end-user traffic from tests you ran yourself in the Vocily dashboard: ?origin=widget,inbound. It can be null on older conversations, meaning unknown.

New values will be added to direction, origin and status over time. Treat them as open sets - never write an exhaustive switch that assumes today’s list is final.

WhatsApp conversations are not in either resource; they are managed in the dashboard.

Pagination

List endpoints return a cursor-paginated envelope, not a bare array:

{
  "data": [ /* … items … */ ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0wOC0wNFQxMDowMDowMC4wMDBaIiwiaSI6Ii4uLiJ9"
}

To fetch the next page, pass the response’s next_cursor back as the cursor query param. When has_more is false, next_cursor is null and you’ve reached the end. Cursors are opaque - don’t parse or construct them. A cursor from a differently sorted list is refused with invalid_cursor rather than quietly handing you page 1. Which lists page: calls, chats, agents, an agent’s versions, its deploy history, its remembered callers, knowledge bases, and the analysis library. These are the lists that grow without limit, so a cursor is the only way to read all of one. Which do not: numbers, WhatsApp numbers, the memory changes for a single call, and the catalogues (models, voices, transcribers, languages, TTS capabilities). Each is bounded by something real - what your workspace holds, or what we offer - and returns a bare array, so building a picker stays one request.

No ?skip= or ?offset=. Both existed until 2026-09-25 and both drift: a row written while you page can appear on two pages or on none. A cursor names the boundary instead, so new rows land on page 1 and the point you are reading from does not move.

Idempotency

POST /v1/calls accepts an Idempotency-Key header (required for API-key callers). Retrying a request with the same key returns the original call instead of placing a second one - safe against network timeouts. Use a fresh UUID per distinct call.

Rate limits

Requests are limited to 300 per minute per key (moving window). Over the limit you get:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0

{ "code": "rate_limited" }

Honor Retry-After (seconds) rather than retrying in a tight loop.

Concurrency headers

Voice concurrency is a shared pool per organization. Every response carries your current usage so you can self-pace bulk dialing:

X-Vocily-Concurrency-Limit: 20
X-Vocily-Concurrency-Used: 17

For large volumes, use scheduled batches in the dashboard rather than a tight POST /v1/calls loop.

Errors

Errors use standard HTTP status codes. The body always carries a detail, and usually a top-level code:

{ "detail": { "code": "insufficient_balance", "message": "Wallet balance is below the reserve for this call." }, "code": "BAD_REQUEST" }

detail is an object: code is the machine-readable reason and message is a sentence safe to log. Every refusal a public endpoint raises carries both. Two responses are shaped by the framework before any endpoint runs, and carry a plain-string detail instead: a 404 for a path that does not exist, and a 405 for a method an existing path does not accept. Both still carry the top-level code (NOT_FOUND, METHOD_NOT_ALLOWED), which is what to branch on — and neither is something a correct client produces. The top-level code is normally the class of failure derived from the status - BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, VALIDATION_ERROR, SERVICE_UNAVAILABLE - but on a 429 and on a malformed-parameter 400 it is the reason itself. So read the reason with one rule that covers every response:

// covers every response, including the flat 429
const reason = (err.detail && err.detail.code) || err.code;

Branch on that. Never branch on message text - we reword messages without notice.

One response does not follow the shape above. A 429 is flat, { "code": "rate_limited" }, with Retry-After and the X-RateLimit-* headers carrying the rest.

Validation errors

A request the API cannot read - a field of the wrong type, out of range, missing, or one we do not accept - is a 422 in the same envelope, with reason validation_error. message names the first problem; errors lists every problem, so one round trip is enough to fix a malformed body:

{
  "detail": {
    "code": "validation_error",
    "message": "model.temperature: Input should be less than or equal to 2 (and 1 more)",
    "errors": [
      { "field": "model.temperature", "message": "Input should be less than or equal to 2", "type": "less_than_equal" },
      { "field": "model.pitch", "message": "Extra inputs are not permitted", "type": "extra_forbidden" }
    ]
  },
  "code": "VALIDATION_ERROR"
}

field is a path from the root of your request - voice.speed, variables[0].key, or query.limit for a query parameter. type is a stable machine code (missing, extra_forbidden, less_than_equal, …); switch on it rather than on message.

Reason codes

Read these from detail.code, except the two marked (top-level).

HTTP	Reason	Meaning
400	`invalid_request`	The request is malformed: a `?version=` that is neither `live` nor a number, an `If-Match` that is not a `document_revision`, or an id a route does not pre-validate (most resource routes answer a malformed id with a `422` or a `404` instead - see the note below). Top-level on routes that do not pre-validate, in `detail.code` where the route checks it itself.
400	`document_invalid`	The value cannot be used, though the field is real and the value well-formed: a hold check-in that lands after the hold ends, an emotion no provider speaks, a backup on the main engine’s own provider, a number this workspace does not hold. The message names the field.
400	`voice_not_found`	`voice.voice_id` (or a backup’s) is not a voice that provider offers for the agent’s language - `GET /v1/voices` lists them.
400	`voice_config_invalid`	The voice block cannot work as sent: an unknown or withdrawn provider, a provider that cannot speak a configured language, or a backup that could never be used. The message names the problem.
400	`invalid_cursor`	The pagination `cursor` is malformed or expired - discard it and refetch page 1.
400	`invalid_direction`	`?direction=` on `GET /v1/calls` accepts only `inbound`, `outbound` or `web`.
400	`idempotency_key_required`	`POST /v1/calls` was sent without an `Idempotency-Key`.
400	`no_from_number`	No usable `from_number` for this call.
402	`insufficient_balance`	Wallet below the reserve needed for the call.
403	`not_public_api`	This endpoint exists, but it is not part of the public API - it serves the Vocily dashboard.
403	`test_number_not_allowed`	`from_number` is Vocily’s shared Test Number - usable only from the dashboard.
403	`test_number_destination_not_allowed`	The destination is not permitted from the shared Test Number.
403	`forbidden`	Your key lacks the permission this action needs. Publishing with `make_live: true` needs `agents:publish`, the permission that decides what real callers hear.
404	`call_not_found` / `chat_not_found` / `agent_not_found`	No such resource. A malformed id also reads as “not found”.
404	`version_not_found`	The requested agent version does not exist.
404	`knowledge_base_not_found` / `analysis_group_not_found` / `analysis_item_not_found` / `memory_fact_not_found` / `memory_subject_not_found`	No such resource in this workspace.
404	`workspace_not_found`	The workspace behind your key no longer exists.
404	`recording_not_available`	The call has no finalized recording yet.
409	`agent_not_published`	The agent has no live version - publish it first. Also returned by `make-live` for a version that is still a draft.
409	`version_already_published`	That version is already frozen; publish a draft instead.
409	`version_live`	The version you are deleting is the live one - make another live first.
409	`version_pinned_by_batch`	An unfinished batch is running on that version; it can be deleted once they finish.
409	`version_undeletable`	`V0` is the version the agent was created with and cannot be deleted.
409	`agent_not_live`	Nothing is live, so there is nothing to take off air.
409	`version_immutable`	That version is published, so it cannot be edited. Branch a draft from it with `POST /v1/agents/{id}/drafts`.
409	`version_document_stale`	Your `If-Match` names an older `document_revision` - someone else changed the agent since you read it. Re-read and retry.
409	`multiple_drafts`	The agent has more than one unpublished draft, so `?version=` cannot be left to guess; name the one you mean.
409	`knowledge_base_conflict`	The knowledge base cannot change as asked; the message says why.
400	`default_language_invalid` / `language_not_supported`	The `language` block names a language the chosen speech model cannot recognise.
400	`transfer_timezone_invalid`	A `builtin_tools.transfer_call.numbers[]` entry names something that is not an IANA timezone.
400	`runtime_variable_invalid` / `duplicate_runtime_variable`	A `variables[]` entry has an unusable key, or the same key twice.
400	`too_many_analysis_groups`	More `analysis_group_ids` than an agent may attach.
400	`prompt_tool_reference_invalid`	The prompt arms a tool with `<tool_name>` that this agent does not have. Build it on the agent’s Tools tab first.
409	`concurrency_exceeded`	All concurrent lines are busy - retry shortly.
409	`workspace_concurrency_exceeded`	This workspace is at its own concurrent-call limit, even though the org has lines free.
409	`carrier_capacity_exceeded`	The carrier account is at its concurrent-call ceiling. Affects every workspace on that account.
422	`validation_error`	The request could not be read: a field of the wrong type, out of range, missing, or not accepted. `detail.errors` lists each one - see Validation errors.
429	`rate_limited` (top-level)	Too many requests - honor `Retry-After`.
501	`provider_not_configured`	Telephony provider credentials are not set up.
502	`provider_error`	The telephony provider rejected or failed the request.

A malformed id (a partial UUID, or one with a stray character such as a trailing }) never crashes the API. On agent, version and custom-analysis routes it is a 422 validation_error whose errors[0].field names the id; on call and chat routes it reads as “not found” (404, call_not_found); anywhere else it is a 400 with top-level code = invalid_request.

Versioning & request IDs

Versioning - the REST surface is pinned by the /v1 path prefix. Response and webhook payloads are additive within a version: fields may be added, never removed or renamed. Breaking changes ship under a new dated version.
Request IDs - every response includes an X-Request-ID header. Include it when contacting support so we can trace the exact request.

Calls

Chats

Phone Numbers

Knowledge Bases

Agents

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Base URL

Authentication

What a key can do

The endpoints

Place a call

List calls

Get a call

Get a recording

List chats

List agents

List phone numbers

Knowledge bases

Webhooks

Voice and text are separate

Idempotency

Rate limits

Concurrency headers

Errors

Validation errors

Reason codes

Versioning & request IDs

​Base URL

​Authentication

​What a key can do

​The endpoints

Place a call

List calls

Get a call

Get a recording

List chats

List agents

List phone numbers

Knowledge bases

Webhooks

​Voice and text are separate

​Pagination

​Idempotency

​Rate limits

​Concurrency headers

​Errors

​Validation errors

​Reason codes

​Versioning & request IDs

Base URL

Authentication

What a key can do

The endpoints

Voice and text are separate

Pagination

Idempotency

Rate limits

Concurrency headers

Errors

Validation errors

Reason codes

Versioning & request IDs