# Vaakyo > Vaakyo builds and runs AI voice agents that answer and place phone calls. Drive it from code with the REST API (/api/v1), webhooks and the MCP server. ## Get started - [Introduction](https://docs.vaakyo.com/overview.md): Vaakyo runs AI voice agents that answer and place phone calls, and it keeps a full record of every call: transcript, timeline, recording, cost and post-call analysis. - [Quickstart](https://docs.vaakyo.com/quickstart.md): This guide takes you from an empty workspace to a finished phone call with cURL: create an API key, create an agent, place a call, wait for it to end, and read what was said. - [Call flow](https://docs.vaakyo.com/concepts/call-flow.md): Every call in Vaakyo moves through a small set of statuses, and this page explains each one: how a call starts, what happens while it runs, how it ends, and what Vaakyo keeps afterwards. - [Glossary](https://docs.vaakyo.com/concepts/glossary.md): Short definitions of the words these docs use, with a link to the page that covers each one in depth. ## Agents - [Agents](https://docs.vaakyo.com/agents/overview.md): An agent is one complete voice agent configuration, and this page describes the agent object, its editor tabs and the endpoints that create and change it. - [Agent tab](https://docs.vaakyo.com/agents/agent.md): The Agent tab holds what the caller hears first and how the agent should behave: its name, welcome message and prompt, with {variables} you fill in for each call. - [LLM tab](https://docs.vaakyo.com/agents/llm.md): The LLM tab picks the model that decides what the agent says and calls its tools, and sets how varied and how long its replies are. - [Voice tab](https://docs.vaakyo.com/agents/voice.md): The Voice tab sets how the agent sounds: the text-to-speech provider and model, the voice, the language it speaks and how fast it talks. Three providers are available: Cartesia (the default, voices in many languages), Sarvam AI (voices built for Hindi, Hinglish and 10 more Indian languages) and ElevenLabs (your ElevenLabs account's voices, cloned ones included, in 32 languages). - [Transcriber tab](https://docs.vaakyo.com/agents/transcriber.md): The Transcriber tab picks the speech-to-text service that turns the caller's speech into text and decides when the caller has finished speaking. - [Call tab](https://docs.vaakyo.com/agents/call.md): The Call tab controls how a conversation runs and ends: interruptions, silence handling, the "are you still there?" check, hanging up with a prompt, the maximum length, calling hours and recording. - [Tools](https://docs.vaakyo.com/agents/tools.md): Tools let the agent call your HTTP endpoints in the middle of a conversation, for example to check free slots, book an appointment or look up an order, and the built-in endcall lets it hang up. - [Knowledge base](https://docs.vaakyo.com/agents/knowledge-base.md): A knowledge base holds your own material (PDFs, text files, web pages and pasted text) so an agent can look up facts about your business during a call, like prices, timings and policies, and answer from them instead of guessing. - [Analytics tab](https://docs.vaakyo.com/agents/analytics.md): The Analytics tab turns on post-call analysis: a short summary of each call and typed fields pulled from its transcript, saved on the call, included in exports and sent in the call.completed webhook. - [Webhook and number](https://docs.vaakyo.com/agents/webhook-and-number.md): The Webhook & number tab sets where the agent's call events are posted and which phone number the agent answers and calls from. - [Testing](https://docs.vaakyo.com/agents/testing.md): Write test scenarios for an agent and run simulated text conversations against it before it goes live: an LLM plays the caller, your agent answers with its real prompt, model and tools, and an LLM judge scores the transcript against your criteria. - [Guardrails](https://docs.vaakyo.com/agents/guardrails.md): The Vaakyo platform team sets guardrails: rules every agent on the platform must follow, in every workspace. They are added to each agent's prompt, and every phone call is checked after it ends. If an agent breaks a rule, the workspace gets a strict notice. If the same agent breaks a rule again within the window, the agent is frozen until the platform team unfreezes it. - [Versions](https://docs.vaakyo.com/agents/versions.md): Every change to an agent is saved as a version, with who made it and what changed field by field, so you can see an agent's history and restore an earlier configuration. ## Calls - [Outbound calls](https://docs.vaakyo.com/calls/outbound.md): You place an outbound call with one request; Vaakyo queues it, dials it when a call slot is free and the agent's calling hours are open, and records everything that happens. - [Campaigns (batch calls)](https://docs.vaakyo.com/calls/batches.md): A campaign calls every contact in a CSV or Excel file with one agent from one phone number: you upload the list, check it, pick a start time, a concurrency cap and retry rules, and Vaakyo works through it inside the calling hours, then gives you the results as a CSV. - [Inbound calls](https://docs.vaakyo.com/calls/inbound.md): When someone dials a phone number connected to one of your agents, that agent answers; this page explains how numbers are set up and how Vaakyo decides whether to take the call. - [Phone numbers](https://docs.vaakyo.com/calls/telephony.md): Vaakyo places and answers phone calls over Plivo. Your workspace's numbers are Plivo numbers, assigned by the Vaakyo team or bought by you in the console, and each one costs a monthly fee from your credits. - [Truecaller verified caller ID](https://docs.vaakyo.com/calls/truecaller.md): Ask for Truecaller's verified caller ID on one of your numbers, and calls from it show your brand name, logo and Truecaller's green verified badge. Agents can also show a reason for each call on the receiver's phone before they pick up. - [Browser calls](https://docs.vaakyo.com/calls/browser.md): A browser call lets you talk to an agent through your microphone, with no phone involved, so you can test a prompt or a tool before the agent calls anyone. - [The call object](https://docs.vaakyo.com/calls/call-object.md): Every call in Vaakyo, outbound, inbound or in the browser, is stored as one call record, and this page describes each of its fields, how to read them, and what they look like for common outcomes. - [Limits and billing](https://docs.vaakyo.com/calls/limits.md): Your workspace can run a fixed number of calls at once and pays for them from a prepaid balance, and this page explains both: concurrency, the queue, credits and how each one affects your calls. ## Webhooks - [Webhooks](https://docs.vaakyo.com/webhooks/overview.md): Vaakyo posts each event of every call to your server as it happens, signed with a secret only you and Vaakyo know, and retries deliveries that fail, so a slow or broken endpoint never affects a live call. - [Webhook events](https://docs.vaakyo.com/webhooks/events.md): This page lists every event Vaakyo sends during a call, when it is sent, and the fields it carries in data. ## MCP server - [MCP server](https://docs.vaakyo.com/mcp/overview.md): Connect Claude, Cursor or any other MCP client to your Vaakyo workspace, and build, test and run voice agents by asking for it in plain language. - [Connect an MCP client](https://docs.vaakyo.com/mcp/quickstart.md): Add Vaakyo's MCP server to your assistant, sign in once in the browser, and check the connection with a first prompt. - [Tools](https://docs.vaakyo.com/mcp/tools.md): Every tool the Vaakyo MCP server exposes, what it needs, and whether your assistant will ask before running it. - [Prompt cheatsheet](https://docs.vaakyo.com/mcp/prompts.md): Prompts to copy into a connected assistant, grouped by task, with the tools each one uses. ## Account - [Composer](https://docs.vaakyo.com/composer.md): Composer is the assistant built into the Vaakyo console. Chat with it to build, debug, analyse and test your voice agents. It does the work for you with the same tools and permissions you have. - [Authentication](https://docs.vaakyo.com/authentication.md): Your code authenticates to Vaakyo with an API key, and this page covers keys, roles and permissions, rate limits, time zones and errors: the conventions every endpoint follows. - [Versioning, deprecation and rate limits](https://docs.vaakyo.com/versioning.md): How the Vaakyo API changes over time, how you hear about it before it affects you, and how fast you may call it. - [CLI](https://docs.vaakyo.com/cli.md): The Vaakyo CLI drives the public API from a terminal or a script: list agents, place calls, read transcripts and check credits. Every command takes --json, so scripts and AI agents can read the output. - [Logs](https://docs.vaakyo.com/logs.md): The console's Logs page shows what happened in your workspace in one place: every call, every webhook delivery, every request your API keys and connected apps made, and the server logs, each with filters you can share as a link and an export to CSV. - [Changelog](https://docs.vaakyo.com/changelog.md): What's new in Vaakyo, newest first. ## API reference - [OpenAPI spec](https://docs.vaakyo.com/openapi.json): every public operation, as OpenAPI 3.1 ### Agents - [List agents](https://docs.vaakyo.com/api-reference/agents/list-agents.md): `GET /api/v1/agents`. Every agent in the workspace, with its full configuration and the {variables} its text uses. - [Create an agent](https://docs.vaakyo.com/api-reference/agents/create-an-agent.md): `POST /api/v1/agents`. Only name is required; every other setting has a sensible default. {variables} in the welcome message or prompt are filled from userdata when a call is placed. - [Get an agent](https://docs.vaakyo.com/api-reference/agents/get-an-agent.md): `GET /api/v1/agents/{agent_id}`. One agent with its full configuration. - [Update an agent](https://docs.vaakyo.com/api-reference/agents/update-an-agent.md): `PUT /api/v1/agents/{agent_id}`. Replaces the whole configuration: read the agent, change what you need and send it all back. Fields you leave out go back to their defaults. - [Delete an agent](https://docs.vaakyo.com/api-reference/agents/delete-an-agent.md): `DELETE /api/v1/agents/{agent_id}`. Deletes the agent and its version history. Its past calls are kept. - [Duplicate an agent](https://docs.vaakyo.com/api-reference/agents/duplicate-an-agent.md): `POST /api/v1/agents/{agent_id}/duplicate`. Creates a copy named (copy) with the same configuration, without the phone number. - [List versions](https://docs.vaakyo.com/api-reference/agents/list-versions.md): `GET /api/v1/agents/{agent_id}/versions`. The agent's saved versions, newest first, with who made each change and what changed. Only the most recent versions are kept (10 by default). - [Get a version](https://docs.vaakyo.com/api-reference/agents/get-a-version.md): `GET /api/v1/agents/{agent_id}/versions/{version}`. One saved version, with the full configuration it had (config). Returns 404 for versions no longer kept. - [Restore a version](https://docs.vaakyo.com/api-reference/agents/restore-a-version.md): `POST /api/v1/agents/{agent_id}/versions/{version}/restore`. Puts an older configuration back. The restore is itself saved as a new version, so it can be undone. - [Create Share](https://docs.vaakyo.com/api-reference/agents/create-share.md): `POST /api/v1/agent-shares`. A link anyone can use to copy this agent (a snapshot of it now) into their own workspace. - [List Shares](https://docs.vaakyo.com/api-reference/agents/list-shares.md): `GET /api/v1/agent-shares`. GET /api/v1/agent-shares - [Revoke Share](https://docs.vaakyo.com/api-reference/agents/revoke-share.md): `DELETE /api/v1/agent-shares/{token}`. DELETE /api/v1/agent-shares/{token} - [Preview Share](https://docs.vaakyo.com/api-reference/agents/preview-share.md): `GET /api/v1/agent-shares/{token}`. Public (no sign-in): what the link copies. - [Copy Share](https://docs.vaakyo.com/api-reference/agents/copy-share.md): `POST /api/v1/agent-shares/{token}/copy`. Copy the shared agent into your current workspace. Parts using a provider your workspace can't use go back to the default; notes says what changed and leftout what to add yourself. - [Draft Pricing](https://docs.vaakyo.com/api-reference/agents/draft-pricing.md): `POST /api/v1/agents/pricing`. The approximate price per minute of an unsaved agent configuration, by component (transcriber, LLM, voice, telephony, platform). Never less than the plan's price per minute (floorapplied). - [Agent Pricing](https://docs.vaakyo.com/api-reference/agents/agent-pricing.md): `GET /api/v1/agents/{agent_id}/pricing`. The agent's approximate price per minute, by component, from typical usage per minute (see assumptions). Calls are charged for what they actually use, never less than the plan's price. - [List Sounds](https://docs.vaakyo.com/api-reference/agents/list-sounds.md): `GET /api/v1/ambient`. The presets, then this workspace's uploads (newest first). Use id as call.ambientsound. - [Upload Sound](https://docs.vaakyo.com/api-reference/agents/upload-sound.md): `POST /api/v1/ambient`. POST /api/v1/ambient - [Sound Audio](https://docs.vaakyo.com/api-reference/agents/sound-audio.md): `GET /api/v1/ambient/{sound}/audio`. The clip as a WAV (16 kHz mono) for a preview. - [Delete Sound](https://docs.vaakyo.com/api-reference/agents/delete-sound.md): `DELETE /api/v1/ambient/{sound}`. DELETE /api/v1/ambient/{sound} - [Generate Prompt](https://docs.vaakyo.com/api-reference/agents/generate-prompt.md): `POST /api/v1/agents/prompt/generate`. Write (or improve) a voice-agent system prompt with Gemini. Nothing is saved. - [List Pins](https://docs.vaakyo.com/api-reference/agents/list-pins.md): `GET /api/v1/agents/pins`. Your pinned agents (ids, in pin order): personal, up to 3. - [Pin Agent](https://docs.vaakyo.com/api-reference/agents/pin-agent.md): `PUT /api/v1/agents/{agent_id}/pin`. Pin an agent to the top of your agents list and the sidebar (409 when 3 are pinned). - [Unpin Agent](https://docs.vaakyo.com/api-reference/agents/unpin-agent.md): `DELETE /api/v1/agents/{agent_id}/pin`. DELETE /api/v1/agents/{agent_id}/pin - [Measured Latency](https://docs.vaakyo.com/api-reference/agents/measured-latency.md): `GET /api/v1/agents/{agent_id}/latency`. Average reply latency over the agent's last 20 finished calls, from their timelines: caller stops -> first LLM token (llm.firsttoken) and -> first audio (tts.firstaudio, the welcome excluded). Voice latency is the difference. ### Agent tests - [List an agent's test scenarios](https://docs.vaakyo.com/api-reference/agent-tests/list-an-agent-s-test-scenarios.md): `GET /api/v1/agents/{agent_id}/tests`. The agent's test scenarios, oldest first, each with a summary of its newest run (lastrun: id, status, score, cost). - [Create a test scenario](https://docs.vaakyo.com/api-reference/agent-tests/create-a-test-scenario.md): `POST /api/v1/agents/{agent_id}/tests`. A scenario: the simulated caller (persona), values for the agent's variables, the most caller turns, the criteria the judge checks and optional stub results for the agent's HTTP tools. - [Suggest test scenarios](https://docs.vaakyo.com/api-reference/agent-tests/suggest-test-scenarios.md): `POST /api/v1/agents/{agent_id}/tests/suggest`. Five scenarios with criteria proposed by the platform's test model from the agent's saved prompt. Nothing is saved: create the ones you want. The model's tokens are charged (ledger kind test). - [Run every test scenario](https://docs.vaakyo.com/api-reference/agent-tests/run-every-test-scenario.md): `POST /api/v1/agents/{agent_id}/tests/run-all`. Queue a run of every scenario of the agent (against its saved version). A workspace runs a few at a time (agenttests.concurrencyperworkspace, 3 by default); the rest wait. Each run is charged for its tokens. - [Get a test scenario](https://docs.vaakyo.com/api-reference/agent-tests/get-a-test-scenario.md): `GET /api/v1/agents/{agent_id}/tests/{scenario_id}`. GET /api/v1/agents/{agent_id}/tests/{scenario_id} - [Update a test scenario](https://docs.vaakyo.com/api-reference/agent-tests/update-a-test-scenario.md): `PUT /api/v1/agents/{agent_id}/tests/{scenario_id}`. PUT /api/v1/agents/{agent_id}/tests/{scenario_id} - [Delete a test scenario](https://docs.vaakyo.com/api-reference/agent-tests/delete-a-test-scenario.md): `DELETE /api/v1/agents/{agent_id}/tests/{scenario_id}`. The scenario and its runs. - [Run a test scenario](https://docs.vaakyo.com/api-reference/agent-tests/run-a-test-scenario.md): `POST /api/v1/agents/{agent_id}/tests/{scenario_id}/runs`. Queue a run of the scenario against the agent's saved version; it starts as soon as the workspace has a free test slot. Poll GET /api/v1/test-runs/{runid} until its status is passed, failed or error. Refused (402) without credits. - [List a scenario's runs](https://docs.vaakyo.com/api-reference/agent-tests/list-a-scenario-s-runs.md): `GET /api/v1/agents/{agent_id}/tests/{scenario_id}/runs`. The scenario's runs, newest first (the last 50 are kept), without transcripts. - [Get a test run](https://docs.vaakyo.com/api-reference/agent-tests/get-a-test-run.md): `GET /api/v1/test-runs/{run_id}`. One run: status, the transcript (agent, caller and tool entries), tool calls, each criterion's result and reason, the score, the judge's improvement summary, tokens per role and the cost. ### Calls - [Place a call](https://docs.vaakyo.com/api-reference/calls/place-a-call.md): `POST /api/v1/agents/{agent_id}/call`. Queues an outbound phone call. Calls are dialled by a worker as soon as one of your workspace's call slots is free and, unless ignorecallwindow is set, inside the agent's calling hours (call.callstarthour to call.callendhour). - [List calls](https://docs.vaakyo.com/api-reference/calls/list-calls.md): `GET /api/v1/calls`. Calls in the workspace, newest first, without transcripts. Page with limit and skip; total is the number of calls matching the filters. - [Get a call](https://docs.vaakyo.com/api-reference/calls/get-a-call.md): `GET /api/v1/calls/{call_id}`. One call with its transcript, usage, cost, and post-call analytics (summary, extracted). - [List call events](https://docs.vaakyo.com/api-reference/calls/list-call-events.md): `GET /api/v1/calls/{call_id}/events`. The call's timeline, oldest first: every step from call.queued to call.completed, with latencies (latencyms) for model and speech steps. The same events are sent to your webhooks. - [Download a recording](https://docs.vaakyo.com/api-reference/calls/download-a-recording.md): `GET /api/v1/calls/{call_id}/recording`. The call's stereo WAV recording (caller on the left channel, agent on the right). Add download=true to get it as an attachment. Returns 404 when the call wasn't recorded. - [End or cancel a call](https://docs.vaakyo.com/api-reference/calls/end-or-cancel-a-call.md): `POST /api/v1/calls/{call_id}/hangup`. Cancels a queued call, or hangs up a call that is ringing or in progress. - [Test Analytics](https://docs.vaakyo.com/api-reference/calls/test-analytics.md): `POST /api/v1/agents/{agent_id}/analytics/test`. Run summary and extraction on a call or transcript and return the result. Nothing is saved. - [Reanalyze Call](https://docs.vaakyo.com/api-reference/calls/reanalyze-call.md): `POST /api/v1/calls/{call_id}/analyze`. Run the agent's current analytics on a finished call again and save the result (for example after adding extraction fields). Webhooks are not sent again. - [Export Calls](https://docs.vaakyo.com/api-reference/calls/export-calls.md): `GET /api/v1/calls/export`. Calls as CSV, newest first: one row per call with its outcome, cost, summary and one column per extracted field (extracted.). At most 50,000 rows. ### Batches - [Upload a contact list](https://docs.vaakyo.com/api-reference/batches/upload-a-contact-list.md): `POST /api/v1/batches/uploads`. Parse a contact list and return a preview: the columns, the detected phone column, the first rows, invalid rows (bad numbers, duplicates) with reasons and which agent variables the columns fill. The file is kept for 24 hours under uploadid; create the batch from it. - [Preview an upload again](https://docs.vaakyo.com/api-reference/batches/preview-an-upload-again.md): `GET /api/v1/batches/uploads/{upload_id}`. The same preview as the upload, with another phone column or agent. - [Create a batch](https://docs.vaakyo.com/api-reference/batches/create-a-batch.md): `POST /api/v1/batches`. Schedule a batch from an upload. Each valid row becomes a contact; the other columns become its userdata. Calls go through the workspace's outbound queue inside the agent's calling hours. - [List batches](https://docs.vaakyo.com/api-reference/batches/list-batches.md): `GET /api/v1/batches`. Batches, newest first, with counts per contact status and progress. - [Get a batch](https://docs.vaakyo.com/api-reference/batches/get-a-batch.md): `GET /api/v1/batches/{batch_id}`. One batch with its counts per contact status, progress and retry rules. - [Delete a batch](https://docs.vaakyo.com/api-reference/batches/delete-a-batch.md): `DELETE /api/v1/batches/{batch_id}`. Delete a finished batch and its contact list. Its calls stay in the call history. - [List a batch's contacts](https://docs.vaakyo.com/api-reference/batches/list-a-batch-s-contacts.md): `GET /api/v1/batches/{batch_id}/contacts`. Contacts in file order: number, userdata, status, attempts and the latest call id. - [Pause a batch](https://docs.vaakyo.com/api-reference/batches/pause-a-batch.md): `POST /api/v1/batches/{batch_id}/pause`. Stop releasing contacts. Calls still waiting in the queue are canceled (their attempt does not count); calls already ringing finish. - [Resume a batch](https://docs.vaakyo.com/api-reference/batches/resume-a-batch.md): `POST /api/v1/batches/{batch_id}/resume`. Carry on calling a paused batch (needs credits). - [Cancel a batch](https://docs.vaakyo.com/api-reference/batches/cancel-a-batch.md): `POST /api/v1/batches/{batch_id}/cancel`. Cancel every contact not called yet and the batch's calls still queued. Calls already ringing or in progress finish normally. - [Download a batch's results (CSV)](https://docs.vaakyo.com/api-reference/batches/download-a-batch-s-results-csv.md): `GET /api/v1/batches/{batch_id}/results`. One row per contact: row, the file's columns, phonee164, status, attempts, lastcallid, lastcallstatus, durationseconds, costpaise, summary, outcome (completed, voicemail, transferred, no-answer, ...) and one extracted. column per extracted field. ### Knowledge bases - [List knowledge bases](https://docs.vaakyo.com/api-reference/knowledge-bases/list-knowledge-bases.md): `GET /api/v1/knowledge-bases`. The workspace's knowledge bases, most recently changed first, with the agents using each. - [Create a knowledge base](https://docs.vaakyo.com/api-reference/knowledge-bases/create-a-knowledge-base.md): `POST /api/v1/knowledge-bases`. An empty knowledge base; add sources to it, then attach it to agents. - [Get a knowledge base](https://docs.vaakyo.com/api-reference/knowledge-bases/get-a-knowledge-base.md): `GET /api/v1/knowledge-bases/{kb_id}`. One knowledge base with its sources and their processing status. - [Rename a knowledge base](https://docs.vaakyo.com/api-reference/knowledge-bases/rename-a-knowledge-base.md): `PATCH /api/v1/knowledge-bases/{kb_id}`. Change the name or description. - [Delete a knowledge base](https://docs.vaakyo.com/api-reference/knowledge-bases/delete-a-knowledge-base.md): `DELETE /api/v1/knowledge-bases/{kb_id}`. Delete it with its sources and passages. Refused (409) while an agent uses it. - [Upload a file](https://docs.vaakyo.com/api-reference/knowledge-bases/upload-a-file.md): `POST /api/v1/knowledge-bases/{kb_id}/sources/file`. A PDF (up to 5 MB and 100 pages), or a UTF-8 text or Markdown file (.txt, .md, up to 10 MB). It is processed in the background: poll the knowledge base until the source is ready. - [Add a web page](https://docs.vaakyo.com/api-reference/knowledge-bases/add-a-web-page.md): `POST /api/v1/knowledge-bases/{kb_id}/sources/url`. Fetch one public web page (HTML, text or PDF, up to 5 MB) and index its text. Links are not followed. Addresses on private networks are refused. - [Add pasted text](https://docs.vaakyo.com/api-reference/knowledge-bases/add-pasted-text.md): `POST /api/v1/knowledge-bases/{kb_id}/sources/text`. Index text you paste (an FAQ, a price list, opening hours). - [Delete a source](https://docs.vaakyo.com/api-reference/knowledge-bases/delete-a-source.md): `DELETE /api/v1/knowledge-bases/{kb_id}/sources/{source_id}`. Remove the source and its passages; agents stop finding it at once. - [Process a source again](https://docs.vaakyo.com/api-reference/knowledge-bases/process-a-source-again.md): `POST /api/v1/knowledge-bases/{kb_id}/sources/{source_id}/reprocess`. Extract and index the source again (a web page is fetched again). Its current passages stay searchable until the new ones are ready. - [Test a search](https://docs.vaakyo.com/api-reference/knowledge-bases/test-a-search.md): `POST /api/v1/knowledge-bases/{kb_id}/search`. Run the search an agent runs during a call, and see the passages it would get with their scores. Passages marked relevant: false score below the cut-off and are not given to agents. ### Webhooks - [List event types](https://docs.vaakyo.com/api-reference/webhooks/list-event-types.md): `GET /api/v1/webhooks/events`. Every event type an endpoint can subscribe to. Subscribe to for all of them. - [List endpoints](https://docs.vaakyo.com/api-reference/webhooks/list-endpoints.md): `GET /api/v1/webhooks`. The workspace's webhook endpoints, newest first. Secrets are never returned here, only a hint. - [Create an endpoint](https://docs.vaakyo.com/api-reference/webhooks/create-an-endpoint.md): `POST /api/v1/webhooks`. Registers a URL to receive call events. The signing secret is in this response only: store it to verify signatures. At most 20 endpoints per workspace. - [Update an endpoint](https://docs.vaakyo.com/api-reference/webhooks/update-an-endpoint.md): `PATCH /api/v1/webhooks/{endpoint_id}`. Changes only the fields you send. - [Delete an endpoint](https://docs.vaakyo.com/api-reference/webhooks/delete-an-endpoint.md): `DELETE /api/v1/webhooks/{endpoint_id}`. Stops deliveries to this endpoint. - [Rotate an endpoint's secret](https://docs.vaakyo.com/api-reference/webhooks/rotate-an-endpoint-s-secret.md): `POST /api/v1/webhooks/{endpoint_id}/rotate-secret`. Issues a new signing secret, returned once. Deliveries are signed with it from now on. - [Send a test event](https://docs.vaakyo.com/api-reference/webhooks/send-a-test-event.md): `POST /api/v1/webhooks/{endpoint_id}/test`. Sends a ping event right away (one attempt, no retries) and returns the delivery, including what your server answered. - [Get the default secret hint](https://docs.vaakyo.com/api-reference/webhooks/get-the-default-secret-hint.md): `GET /api/v1/webhooks/default-secret`. A hint of the workspace's default secret, which signs deliveries to agents' own webhookurl. - [Rotate the default secret](https://docs.vaakyo.com/api-reference/webhooks/rotate-the-default-secret.md): `POST /api/v1/webhooks/default-secret/rotate`. Issues a new default secret, returned once. - [List deliveries](https://docs.vaakyo.com/api-reference/webhooks/list-deliveries.md): `GET /api/v1/webhooks/deliveries`. The delivery log, newest first. status takes several values separated by commas (pending, delivered, failed). - [Get a delivery](https://docs.vaakyo.com/api-reference/webhooks/get-a-delivery.md): `GET /api/v1/webhooks/deliveries/{delivery_id}`. One delivery with the exact body sent and the response received. - [Retry a delivery](https://docs.vaakyo.com/api-reference/webhooks/retry-a-delivery.md): `POST /api/v1/webhooks/deliveries/{delivery_id}/retry`. Sends the delivery once more, now. It does not restart the automatic retry schedule. ### Catalog - [Get the catalog](https://docs.vaakyo.com/api-reference/catalog/get-the-catalog.md): `GET /api/v1/catalog`. The models and languages an agent can use: LLM models, text-to-speech and speech-to-text models, and transcriber providers. - [List voices](https://docs.vaakyo.com/api-reference/catalog/list-voices.md): `GET /api/v1/voices`. Voices for voice.voiceid, filtered by language, gender or a search term. - [Preview a voice](https://docs.vaakyo.com/api-reference/catalog/preview-a-voice.md): `GET /api/v1/voices/{voice_id}/preview`. Speaks text with the voice and returns MP3 audio. - [List providers](https://docs.vaakyo.com/api-reference/catalog/list-providers.md): `GET /api/v1/providers`. Every speech, model and telephony provider, and whether your workspace may use it (usable). - [Model Cards](https://docs.vaakyo.com/api-reference/catalog/model-cards.md): `GET /api/v1/catalog/models`. What the agent editor's model cards show: typical figures per model (masters modelprofiles), presets built from options that exist, and this workspace's price per minute. Never the providers' own prices or keys. - [Llm Models](https://docs.vaakyo.com/api-reference/catalog/llm-models.md): `GET /api/v1/catalog/llm-models`. The models an agent can use with an LLM provider. custommodels: any other model id the provider accepts may be typed in (OpenRouter ids, Bedrock inference profiles, Azure deployments). ### Phone numbers - [List phone numbers](https://docs.vaakyo.com/api-reference/numbers/list-phone-numbers.md): `GET /api/v1/numbers`. The phone numbers assigned to your workspace, and the agent that answers each. - [Connect a number to an agent](https://docs.vaakyo.com/api-reference/numbers/connect-a-number-to-an-agent.md): `POST /api/v1/numbers/{number}/connect`. Routes inbound calls on one of your numbers to an agent. The number moves off any other agent. - [Search Numbers](https://docs.vaakyo.com/api-reference/numbers/search-numbers.md): `GET /api/v1/numbers/search`. Numbers you can rent, with their monthly and setup price in the workspace's currency (paise or cents; INR at today's rate). - [Buy Number](https://docs.vaakyo.com/api-reference/numbers/buy-number.md): `POST /api/v1/numbers/buy`. Rent a number: setup and the first month are taken from your credits now, then each month's rent on its date. The number is ready to connect to an agent. - [Release Number](https://docs.vaakyo.com/api-reference/numbers/release-number.md): `DELETE /api/v1/numbers/{number}`. Stop renting a number you rented (no refund for the current month; cannot be undone). ### Tools - [Test a tool](https://docs.vaakyo.com/api-reference/tools/test-a-tool.md): `POST /api/v1/tools/test`. Runs an HTTP tool once with the arguments you give, exactly as an agent would mid-call, and shows what the model would receive. ### Workspace - [Get the workspace](https://docs.vaakyo.com/api-reference/workspace/get-the-workspace.md): `GET /api/v1/workspace`. The workspace your key (or X-Workspace-ID) points at: its status, credit balance and member count. - [Rename the workspace](https://docs.vaakyo.com/api-reference/workspace/rename-the-workspace.md): `PATCH /api/v1/workspace`. PATCH /api/v1/workspace - [Get call limits](https://docs.vaakyo.com/api-reference/workspace/get-call-limits.md): `GET /api/v1/workspace/limits`. How many calls may run at once, how many are running and queued, and any pending request for a higher limit. - [List limit requests](https://docs.vaakyo.com/api-reference/workspace/list-limit-requests.md): `GET /api/v1/workspace/limits/requests`. Requests for a higher concurrency limit, newest first. - [Request a higher limit](https://docs.vaakyo.com/api-reference/workspace/request-a-higher-limit.md): `POST /api/v1/workspace/limits/requests`. Asks the Vaakyo team to raise the concurrent-call limit. Only one request can wait for review at a time. - [List members](https://docs.vaakyo.com/api-reference/workspace/list-members.md): `GET /api/v1/members`. Everyone in the workspace and their role. - [Change a member's role](https://docs.vaakyo.com/api-reference/workspace/change-a-member-s-role.md): `PATCH /api/v1/members/{user_id}`. Only an owner can grant or take away the owner role, and a workspace always keeps one owner. - [Remove a member](https://docs.vaakyo.com/api-reference/workspace/remove-a-member.md): `DELETE /api/v1/members/{user_id}`. The last owner can't be removed. - [List invites](https://docs.vaakyo.com/api-reference/workspace/list-invites.md): `GET /api/v1/invites`. Pending invites that haven't expired. - [Invite a member](https://docs.vaakyo.com/api-reference/workspace/invite-a-member.md): `POST /api/v1/invites`. Emails an invite link. A newer invite to the same email replaces the older one. Plans cap members, counting pending invites. - [Revoke an invite](https://docs.vaakyo.com/api-reference/workspace/revoke-an-invite.md): `DELETE /api/v1/invites/{invite_id}`. DELETE /api/v1/invites/{invite_id} - [List API keys](https://docs.vaakyo.com/api-reference/workspace/list-api-keys.md): `GET /api/v1/keys`. Active keys. Only the prefix of each key is shown. - [Create an API key](https://docs.vaakyo.com/api-reference/workspace/create-an-api-key.md): `POST /api/v1/keys`. The full key is in this response only; store it somewhere safe. Keys act as a developer in this workspace. - [Revoke an API key](https://docs.vaakyo.com/api-reference/workspace/revoke-an-api-key.md): `DELETE /api/v1/keys/{key_id}`. The key stops working immediately. - [Get KYC](https://docs.vaakyo.com/api-reference/workspace/get-kyc.md): `GET /api/v1/kyc`. The workspace's business details and uploaded documents. - [Save KYC details](https://docs.vaakyo.com/api-reference/workspace/save-kyc-details.md): `PUT /api/v1/kyc`. Saves the business details as a draft. Can't be changed once submitted or approved (409). - [Upload a KYC document](https://docs.vaakyo.com/api-reference/workspace/upload-a-kyc-document.md): `POST /api/v1/kyc/documents`. A PDF, PNG or JPG, sent as multipart/form-data. kind is one of the document kinds in Get settings lists (kycdocumentkinds). - [Download a KYC document](https://docs.vaakyo.com/api-reference/workspace/download-a-kyc-document.md): `GET /api/v1/kyc/documents/{doc_id}`. GET /api/v1/kyc/documents/{doc_id} - [Delete a KYC document](https://docs.vaakyo.com/api-reference/workspace/delete-a-kyc-document.md): `DELETE /api/v1/kyc/documents/{doc_id}`. DELETE /api/v1/kyc/documents/{doc_id} - [Submit KYC](https://docs.vaakyo.com/api-reference/workspace/submit-kyc.md): `POST /api/v1/kyc/submit`. Sends the details and documents for review. Every required field and document must be there (422 names what's missing). - [Search](https://docs.vaakyo.com/api-reference/workspace/search.md): `GET /api/v1/search`. Finds agents, calls and members by name, number or id, limited to what your role can see. - [Get settings lists](https://docs.vaakyo.com/api-reference/workspace/get-settings-lists.md): `GET /api/v1/masters`. Lists the console's forms use: business types, KYC document kinds, languages, Indian states, the currency and the GST rate. - [Set System Logs](https://docs.vaakyo.com/api-reference/workspace/set-system-logs.md): `PATCH /api/v1/workspace/system-logs`. Show or hide the server log (Logs > System) for this workspace; off by default. - [Update Profile](https://docs.vaakyo.com/api-reference/workspace/update-profile.md): `PATCH /api/v1/workspace/profile`. Update the organization's address, GSTIN and contact details after KYC approval. Legal name, business type and PAN can't be changed here. Invoices already issued keep their details. - [Workspace Rules](https://docs.vaakyo.com/api-reference/workspace/workspace-rules.md): `GET /api/v1/guardrails/rules`. The platform rules every agent must follow (enabled ones), and how strikes work. - [Workspace Summary](https://docs.vaakyo.com/api-reference/workspace/workspace-summary.md): `GET /api/v1/guardrails/summary`. The dashboard notice: violation incidents not yet acknowledged, and frozen agents. - [Workspace Incidents](https://docs.vaakyo.com/api-reference/workspace/workspace-incidents.md): `GET /api/v1/guardrails/incidents`. The workspace's guardrail incidents, newest first. - [Workspace Incident](https://docs.vaakyo.com/api-reference/workspace/workspace-incident.md): `GET /api/v1/guardrails/incidents/{incident_id}`. GET /api/v1/guardrails/incidents/{incident_id} - [Acknowledge](https://docs.vaakyo.com/api-reference/workspace/acknowledge.md): `POST /api/v1/guardrails/incidents/{incident_id}/acknowledge`. Acknowledge a notice (clears it from the dashboard banner; the strike stays). - [Appeal](https://docs.vaakyo.com/api-reference/workspace/appeal.md): `POST /api/v1/guardrails/incidents/{incident_id}/appeal`. Ask the platform team to review an incident (a note: why it's wrong, or what was fixed). - [Overview](https://docs.vaakyo.com/api-reference/workspace/overview.md): `GET /api/v1/caller-id`. The workspace's Truecaller requests (newest first), what verification costs it, the business categories to choose from and whether it can ask. - [Ask](https://docs.vaakyo.com/api-reference/workspace/ask.md): `POST /api/v1/caller-id`. Ask for Truecaller verification of one of the workspace's numbers: the brand name callers see (3-40 characters), a square logo (PNG or JPEG, under 2 MB, at least 200×200), the business category and the usual reason for calling. The platform team reviews it; fees start once verified. - [Logo](https://docs.vaakyo.com/api-reference/workspace/logo.md): `GET /api/v1/caller-id/{request_id}/logo`. GET /api/v1/caller-id/{request_id}/logo - [Withdraw](https://docs.vaakyo.com/api-reference/workspace/withdraw.md): `POST /api/v1/caller-id/{request_id}/withdraw`. POST /api/v1/caller-id/{request_id}/withdraw - [Stop](https://docs.vaakyo.com/api-reference/workspace/stop.md): `POST /api/v1/caller-id/{request_id}/remove`. Stop a verification (its monthly fee stops; Truecaller delists the number). - [India's states and cities](https://docs.vaakyo.com/api-reference/workspace/india-s-states-and-cities.md): `GET /api/v1/locations/india`. All 36 states and union territories of India, sorted by name, each with its two-digit GST state code and its cities and towns (district headquarters and other towns, sorted). Address fields (state, city) elsewhere in the API must use these names. No authentication; cache it: the response carries an ETag and Cache-Control, and If-None-Match returns 304. ### Billing - [Get the balance](https://docs.vaakyo.com/api-reference/billing/get-the-balance.md): `GET /api/v1/billing`. Credits left, the price per minute, and roughly how many minutes that buys. - [List credit changes](https://docs.vaakyo.com/api-reference/billing/list-credit-changes.md): `GET /api/v1/billing/ledger`. Every change to the balance (top-ups, call charges, adjustments), newest first. - [List payments](https://docs.vaakyo.com/api-reference/billing/list-payments.md): `GET /api/v1/billing/payments`. The last 100 top-up payments. - [Start a top-up](https://docs.vaakyo.com/api-reference/billing/start-a-top-up.md): `POST /api/v1/billing/topup`. Creates a payment for a credit pack (packid) or a custom amount (amountpaise). GST is added on top. - [Complete a payment](https://docs.vaakyo.com/api-reference/billing/complete-a-payment.md): `POST /api/v1/billing/payments/{payment_id}/complete`. The payment gateway's callback (simulated). A created payment completes once; on success the credits are added and an invoice is issued. - [Get the plan](https://docs.vaakyo.com/api-reference/billing/get-the-plan.md): `GET /api/v1/billing/plan`. Your plan, any overrides the Vaakyo team set for your workspace, and the values in effect. - [List credit packs](https://docs.vaakyo.com/api-reference/billing/list-credit-packs.md): `GET /api/v1/billing/packs`. Credit packs on sale. - [List invoices](https://docs.vaakyo.com/api-reference/billing/list-invoices.md): `GET /api/v1/billing/invoices`. GET /api/v1/billing/invoices - [Download an invoice](https://docs.vaakyo.com/api-reference/billing/download-an-invoice.md): `GET /api/v1/billing/invoices/{invoice_id}/pdf`. The invoice as a PDF. - [Switch to another plan](https://docs.vaakyo.com/api-reference/billing/switch-to-another-plan.md): `POST /api/v1/billing/plan`. Move the workspace to a public, self-serve plan at once (workspace owners). A plan with a monthly fee takes the first month from credits now (402 when the credits don't cover it) and then every 30 days, each with an invoice, and grants its includedminutes for each paid month (unused minutes don't roll over); a plan without one ends the monthly charges. There is no proration and no refund of what was paid for the old plan. Custom plans are arranged with sales instead. - [Minutes used in a billing month](https://docs.vaakyo.com/api-reference/billing/minutes-used-in-a-billing-month.md): `GET /api/v1/billing/usage`. Call minutes, calls and spend per day for one calendar month (the billing cycle). - [The plans on offer](https://docs.vaakyo.com/api-reference/billing/the-plans-on-offer.md): `GET /api/v1/billing/plans`. Public active plans, with the workspace's current one marked, priced in the workspace's currency (priceperminutepaise, and monthlyfeepaise, taken from credits every 30 days). canswitch says whether this caller (a workspace owner) can move to a plan at once with POST /api/billing/plan; custom plans go to sales (ctaurl, else contactemail). A plan with a fee may include call minutes in each paid month (includedminutes); planminutesleftseconds, planminutestotalseconds and planminutescycleend say where the current cycle stands. - [Extra call lines](https://docs.vaakyo.com/api-reference/billing/extra-call-lines.md): `GET /api/v1/billing/lines`. The workspace's extra call lines: extralines, the monthly priceperlinepaise in its currency, the cycle (linespaiduntil), the plan's baseconcurrencylimit, the total concurrencylimit and how many more it may add (canadd, up to the platform's ceiling). - [Buy extra call lines](https://docs.vaakyo.com/api-reference/billing/buy-extra-call-lines.md): `POST /api/v1/billing/lines`. Add concurrent call lines (workspace owners), charged from credits now: a full month, or what is left of the running lines cycle (prorated by the day). Then every 30 days with an invoice; unpaid past the grace period, the lines are removed. 402 when the credits don't cover it. - [Remove extra call lines](https://docs.vaakyo.com/api-reference/billing/remove-extra-call-lines.md): `POST /api/v1/billing/lines/remove`. Remove lines at once. No refund for the rest of the cycle. - [Redeem a coupon](https://docs.vaakyo.com/api-reference/billing/redeem-a-coupon.md): `POST /api/v1/billing/coupons/redeem`. A credit coupon adds its credits now; a top-up bonus coupon waits for the next paid top-up (the checkout shows the bonus). ### Observability - [Get call stats](https://docs.vaakyo.com/api-reference/observability/get-call-stats.md): `GET /api/v1/stats`. Totals, a per-day series and the busiest agents over the last days days (India time). - [List server logs](https://docs.vaakyo.com/api-reference/observability/list-server-logs.md): `GET /api/v1/logs`. Log lines for your workspace, newest first. level=warning shows warnings and errors; source matches a prefix. - [List log sources](https://docs.vaakyo.com/api-reference/observability/list-log-sources.md): `GET /api/v1/logs/sources`. GET /api/v1/logs/sources - [Get server settings](https://docs.vaakyo.com/api-reference/observability/get-server-settings.md): `GET /api/v1/settings`. Which providers the server has keys for, its public URL, version and retention settings. - [Healthz](https://docs.vaakyo.com/api-reference/observability/healthz.md): `GET /api/v1/healthz`. GET /api/v1/healthz - [Healthz](https://docs.vaakyo.com/api-reference/observability/healthz-get.md): `GET /api/v1/health`. GET /api/v1/health - [List API requests](https://docs.vaakyo.com/api-reference/observability/list-api-requests.md): `GET /api/v1/logs/requests`. Requests made to the API with this workspace's API keys or connected apps (OAuth), newest first: method, path (no query string), status, latency, key and request id. Kept for 30 days. - [Keys seen in the API request log](https://docs.vaakyo.com/api-reference/observability/keys-seen-in-the-api-request-log.md): `GET /api/v1/logs/requests/keys`. The API keys and connected apps that made requests in the last 30 days (for the key filter). ### Account and sign-in - [Sign up](https://docs.vaakyo.com/api-reference/account/sign-up.md): `POST /api/v1/auth/signup`. Creates a user and a workspace (waiting for KYC) and signs in. Returns a session token for Authorization: Bearer. - [Sign in](https://docs.vaakyo.com/api-reference/account/sign-in.md): `POST /api/v1/auth/login`. Exchanges an email and password for a session token. With two-step verification on, the answer is {"requires2fa": true, "challenge": "..."}: finish with Sign in with a code. Repeated failures from one address return 429 for a few minutes. - [Sign in with a code](https://docs.vaakyo.com/api-reference/account/sign-in-with-a-code.md): `POST /api/v1/auth/login/2fa`. The second step of signing in: the challenge from Sign in (valid 5 minutes) and a code from the authenticator app or a recovery code. - [Who am I](https://docs.vaakyo.com/api-reference/account/who-am-i.md): `GET /api/v1/auth/me`. The caller, the current workspace and its permissions. Works with an API key too: then the user is the key (key:) with the developer role. - [Sign out](https://docs.vaakyo.com/api-reference/account/sign-out.md): `POST /api/v1/auth/logout`. Ends the current session. With an API key it does nothing. - [Get an invite](https://docs.vaakyo.com/api-reference/account/get-an-invite.md): `GET /api/v1/invites/{token}`. What an invite link is for, before accepting it. No authentication: the token is the secret. - [Accept an invite](https://docs.vaakyo.com/api-reference/account/accept-an-invite.md): `POST /api/v1/invites/{token}/accept`. Joins the workspace and signs in. New users also send name; existing users send their current password. - [Get your account](https://docs.vaakyo.com/api-reference/account/get-your-account.md): `GET /api/v1/account`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Update your name](https://docs.vaakyo.com/api-reference/account/update-your-name.md): `PATCH /api/v1/account`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Delete your account](https://docs.vaakyo.com/api-reference/account/delete-your-account.md): `DELETE /api/v1/account`. Signs out everywhere and removes you from every workspace. The last owner of a workspace with other members must hand over ownership first (409). - [Change your email](https://docs.vaakyo.com/api-reference/account/change-your-email.md): `POST /api/v1/account/email`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Change your password](https://docs.vaakyo.com/api-reference/account/change-your-password.md): `POST /api/v1/account/password`. Signs out your other sessions. - [List your sessions](https://docs.vaakyo.com/api-reference/account/list-your-sessions.md): `GET /api/v1/account/sessions`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Revoke a session](https://docs.vaakyo.com/api-reference/account/revoke-a-session.md): `DELETE /api/v1/account/sessions/{session_id}`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Sign out other sessions](https://docs.vaakyo.com/api-reference/account/sign-out-other-sessions.md): `POST /api/v1/account/sessions/revoke-others`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403. - [Start two-step setup](https://docs.vaakyo.com/api-reference/account/start-two-step-setup.md): `POST /api/v1/account/2fa/setup`. Returns a secret and an otpauth:// URL for an authenticator app. Confirm with Turn on two-step verification. - [Turn on two-step verification](https://docs.vaakyo.com/api-reference/account/turn-on-two-step-verification.md): `POST /api/v1/account/2fa/enable`. Confirms setup with a code from the app and returns one-time recovery codes (shown once). - [Turn off two-step verification](https://docs.vaakyo.com/api-reference/account/turn-off-two-step-verification.md): `POST /api/v1/account/2fa/disable`. Needs a signed-in user session (Authorization: Bearer from Sign in); API keys get 403.