# VoiceDock Documentation

> VoiceDock is a voice AI platform. Build AI voice assistants that handle phone calls, run custom functions, and integrate with your stack. The full page contents are available at /llms-full.txt.

## Pages

- [Changelog](https://doc.voicedock.ai/docs/changelog): Notable changes to the VoiceDock platform, API, and documentation.
- [Introduction](https://doc.voicedock.ai/docs/introduction): VoiceDock is a voice AI platform built by Flireo B.V., running on our own HMS Sovereign orchestration engine. Build AI voice assistants that handle phone calls, run custom functions, and integrate with your stack.
- [Analysis Templates](https://doc.voicedock.ai/docs/configuration/analysis-templates): Define reusable configurations for post-call analysis and reference them across multiple assistants.
- [Custom Tools](https://doc.voicedock.ai/docs/configuration/custom-tools): Allow your AI assistant to execute functions during calls, like looking up customer information or booking appointments.
- [MCP Servers](https://doc.voicedock.ai/docs/configuration/mcp-servers): Give an assistant the tools of an MCP server during a call, such as searching a mailbox or looking up a customer in your CRM, with the headers you choose for authentication.
- [SIP Trunks](https://doc.voicedock.ai/docs/configuration/sip-trunks): Configure SIP trunks to enable call transfers from your AI assistant to external phone systems.
- [Tool Templates](https://doc.voicedock.ai/docs/configuration/tool-templates): Define reusable tool configurations that can be easily added to multiple assistants.
- [Assistants](https://doc.voicedock.ai/docs/core-concepts/assistants): Assistants are AI-powered voice entities that handle phone conversations, each with its own personality, knowledge, and capabilities.
- [Calls](https://doc.voicedock.ai/docs/core-concepts/calls): Calls represent phone conversations handled by your AI assistants. HMS Sovereign supports both inbound and outbound calls.
- [Phone Numbers](https://doc.voicedock.ai/docs/core-concepts/phone-numbers): Phone numbers are the entry point for your AI assistants. Incoming calls to registered numbers are handled by the assigned assistant.
- [Webhooks](https://doc.voicedock.ai/docs/core-concepts/webhooks): Webhooks allow you to receive real-time notifications about call events via HTTP POST requests to your configured endpoint.
- [AI Generation](https://doc.voicedock.ai/docs/features/ai-generation): Describe what your assistant should do in plain language, and have a system prompt written for it — for the model it actually runs on.
- [Arena: test calls](https://doc.voicedock.ai/docs/features/arena): Test your assistant with real phone calls: a test caller with a persona, a script of events, and a verdict per criterion.
- [Autonomous Silence Handling](https://doc.voicedock.ai/docs/features/autonomous-silence-handling): Intelligently detect and respond to prolonged silence during calls, preventing calls from hanging indefinitely.
- [Call Analysis](https://doc.voicedock.ai/docs/features/call-analysis): Extract structured data from call transcripts using AI to automatically capture sentiment, intents, and outcomes.
- [Call Transfers](https://doc.voicedock.ai/docs/features/call-transfers): Transfer calls from your AI assistant to human agents, other departments, or external numbers using SIP trunks or the built-in transfer tool.
- [Outbound Campaigns](https://doc.voicedock.ai/docs/features/campaigns): Set up automated outbound calling campaigns to reach leads with personalized AI conversations.
- [Closing Phrases](https://doc.voicedock.ai/docs/features/closing-phrases): End the call as soon as the assistant says one of your closing sentences.
- [Privacy & Compliance](https://doc.voicedock.ai/docs/features/privacy-compliance): VoiceDock provides Recording Consent (DTMF opt-in) and GDPR Mode for privacy-conscious deployments.
- [Voicemail Detection](https://doc.voicedock.ai/docs/features/voicemail-detection): Detect voicemail systems on outbound calls and optionally leave a pre-configured message.
- [Web Calls](https://doc.voicedock.ai/docs/features/web-calls): Let users speak directly to an AI assistant from their browser via WebRTC, no phone number required.
- [Workflow definitions](https://doc.voicedock.ai/docs/features/workflow-definitions): The workflow definition contract (v1): every field of nodes and edges, the validation rules, and a complete working example.
- [Workflows](https://doc.voicedock.ai/docs/features/workflows): Build multi-step call flows on a visual canvas: conversation steps, background tool calls, human transfers and clean endings — with one assistant supplying the voice and call settings.
- [Authentication](https://doc.voicedock.ai/docs/get-started/authentication): All API requests require authentication using a Bearer token in the Authorization header.
- [Quickstart](https://doc.voicedock.ai/docs/get-started/quickstart): Create your first AI voice assistant and make it available on a phone number in minutes.
- [BYOK Setup](https://doc.voicedock.ai/docs/integrations/byok-setup): Bring Your Own Key allows you to use your own API keys for AI providers, giving you control over costs and model access.
- [ElevenLabs Realtime Integration](https://doc.voicedock.ai/docs/integrations/elevenlabs-realtime-integration): Use ElevenLabs Realtime for low-latency voice conversation with ElevenLabs voices, in one connection.
- [ElevenLabs Eleven v4](https://doc.voicedock.ai/docs/integrations/elevenlabs-v4-integration): Use ElevenLabs Eleven v4 and Eleven v4 Turbo as the voice of a pipeline assistant: more expressive speech, audio tags and more than 90 languages.
- [MCP Server](https://doc.voicedock.ai/docs/integrations/mcp-server): Connect AI coding assistants like Claude Code and Cursor to your VoiceDock account via the hosted Model Context Protocol server — just sign in, no API key to paste.
- [OpenAI GPT-Live Integration](https://doc.voicedock.ai/docs/integrations/openai-gpt-live-integration): Use OpenAI GPT-Live for full-duplex speech-to-speech conversation, with reasoning and tools handled by a backend model.
- [Provider Pricing](https://doc.voicedock.ai/docs/integrations/provider-pricing): Reference pricing for STT, LLM, and TTS providers used with HMS Sovereign.
- [WhatsApp calling](https://doc.voicedock.ai/docs/integrations/whatsapp-calling): Let WhatsApp users call your VoiceDock number from the chat with your business, and have your assistant answer as it does a phone call.
- [xAI Grok Integration](https://doc.voicedock.ai/docs/integrations/xai-grok-integration): Use xAI Grok Realtime API for speech-to-speech conversation with sub-700ms latency.
- [Data Processing Agreement](https://doc.voicedock.ai/docs/guides/data-processing-agreement): How to obtain the VoiceDock Data Processing Agreement, and why it is released on request rather than published here.
- [Prompting per Model](https://doc.voicedock.ai/docs/guides/prompting-per-model): The same prompt does not work on every voice model. What you can steer, what the platform decides, and what to write for a pipeline, for Gemini Live, for GPT-Live and for Grok Realtime.
- [VoiceDock, Flireo & HMS Sovereign](https://doc.voicedock.ai/docs/platform/about): How our company (Flireo B.V.), our product (VoiceDock), and our orchestration technology (HMS Sovereign) relate.
- [Billing & Credits](https://doc.voicedock.ai/docs/platform/billing): HMS Sovereign uses a credits-based billing system where you purchase credits upfront and consume them as you make and receive calls.
- [Dashboard Security](https://doc.voicedock.ai/docs/platform/dashboard-security): Authentication model, access controls, and security measures for all HMS Sovereign dashboard users.
- [EU-resident configuration](https://doc.voicedock.ai/docs/platform/eu-data-sovereignty): How to configure an assistant so speech-to-text, the language model and text-to-speech all process inside the EU.
- [Voice Selection Psychology](https://doc.voicedock.ai/docs/platform/voice-selection-psychology): How voice selection impacts caller behavior and why slightly robotic voices can outperform natural voices in transactional use cases.
- [Whitelabel](https://doc.voicedock.ai/docs/platform/whitelabel): Build your own branded AI calling business with custom portals where clients sign up, purchase credits, and make AI calls under your brand.
- [Error Codes](https://doc.voicedock.ai/docs/reference/error-codes): Complete reference of all error codes returned by the VoiceDock API with explanations and recommended actions.
- [Rate Limits](https://doc.voicedock.ai/docs/reference/rate-limits): API rate limits, response headers, and best practices for staying within limits.
- [Troubleshooting](https://doc.voicedock.ai/docs/reference/troubleshooting): Common issues when integrating with HMS Sovereign and how to resolve them.
- [Node.js SDK](https://doc.voicedock.ai/docs/sdks/node): The official Node.js and TypeScript SDK for VoiceDock, with no runtime dependencies.
- [Build a voice agent](https://doc.voicedock.ai/docs/tutorials/build-a-voice-agent): Configure an assistant from scratch in the VoiceDock dashboard, then place a live test call.
- [Put your assistant on a phone number](https://doc.voicedock.ai/docs/tutorials/put-your-assistant-on-a-phone-number): Request a managed number to test and set up your assistant, or connect your own number over a SIP trunk to go live with real callers.
- [Review your calls](https://doc.voicedock.ai/docs/tutorials/review-your-calls): Listen back to calls, read transcripts and summaries, and capture the same answers from every call with an analysis template.
- [Assistant Request Webhook](https://doc.voicedock.ai/docs/webhooks/assistant-request): Called before an inbound call is answered, allowing dynamic assistant configuration based on caller information.
- [End of Call Report Webhook](https://doc.voicedock.ai/docs/webhooks/end-of-call-report): Called after a call ends with a summary and optional structured analysis for CRM integrations.
- [Webhooks Overview](https://doc.voicedock.ai/docs/webhooks/overview): Receive real-time notifications about call events via HTTP POST requests to your configured endpoint.
- [Webhook Security](https://doc.voicedock.ai/docs/webhooks/security): Verify HMAC-SHA256 webhook signatures to ensure requests come from HMS Sovereign.
- [Status Update Webhook](https://doc.voicedock.ai/docs/webhooks/status-update): Called when the call status changes to track the call lifecycle in your systems.
- [Tool Calls Webhook](https://doc.voicedock.ai/docs/webhooks/tool-calls): Called when the AI assistant needs to execute a custom tool or function during a conversation.
- [List all assistants](https://doc.voicedock.ai/docs/api/assistants/listAssistants): Retrieve all AI voice assistants in your organization.
- [Create a new assistant](https://doc.voicedock.ai/docs/api/assistants/createAssistant): Create a new AI voice assistant with custom STT, LLM, and TTS configurations. Beyond `name`, a pipeline agent also needs `tts_config`: a voice is provider-specific, so there is no default the platform can pick for you. A realtime (speech-to-speech) agent needs neither `stt_config` nor `tts_config`; everything else falls back to a platform default.
- [Get an assistant](https://doc.voicedock.ai/docs/api/assistants/getAssistant): Retrieve a specific assistant by ID.
- [Update an assistant](https://doc.voicedock.ai/docs/api/assistants/updateAssistant): Update an existing assistant. Only provided fields will be updated.
- [Delete an assistant](https://doc.voicedock.ai/docs/api/assistants/deleteAssistant): Delete an assistant. Any phone numbers assigned to this assistant will have their assistant_id set to null.
- [List all phone numbers](https://doc.voicedock.ai/docs/api/numbers/listNumbers): Retrieve all phone numbers in your organization with their assigned agents, transfer trunks and workflows.
- [Register a phone number](https://doc.voicedock.ai/docs/api/numbers/createNumber): Register a new phone number in your organization. The number must be configured with your SIP provider to forward calls to VoiceDock.
- [Get a phone number](https://doc.voicedock.ai/docs/api/numbers/getNumber): Retrieve a specific phone number by ID.
- [Update a phone number](https://doc.voicedock.ai/docs/api/numbers/updateNumber): Update the agent assignment, transfer trunk or attached workflow for a phone number.
- [Delete a phone number](https://doc.voicedock.ai/docs/api/numbers/deleteNumber): Remove a phone number from your organization.
- [Get WhatsApp calling status](https://doc.voicedock.ai/docs/api/numbers/getNumberWhatsapp): Whether WhatsApp calling is set up on this number, and if so, its status. The SIP password is never returned. See the [WhatsApp calling guide](/docs/integrations/whatsapp-calling).
- [Turn off WhatsApp calling](https://doc.voicedock.ai/docs/api/numbers/deleteNumberWhatsapp): Stop taking WhatsApp calls on this number and remove the stored SIP password. The change is applied in the background: the response is `202` with status `disabling`, and `GET` shows `off` once it is done. Turn off calling for the number at Meta as well, or WhatsApp users keep seeing a call button that no longer reaches your assistant. Phone calls to the number are not affected.
- [Turn on WhatsApp calling](https://doc.voicedock.ai/docs/api/numbers/updateNumberWhatsapp): Give VoiceDock the SIP password Meta generated for this number, so that WhatsApp calls to the number reach your assistant. Do this after you have turned on calling over SIP for the number at Meta; the [WhatsApp calling guide](/docs/integrations/whatsapp-calling) has every step.

The change is applied in the background: the response is `202` with status `pending`, and `GET` shows `active` once it is done, usually within a minute. On a number where WhatsApp calling is already set up, this replaces the stored password, for example after you reset it at Meta.

The number must be active and must not already receive its calls through another SIP provider, such as your own SIP trunk. An organization can use WhatsApp calling on up to 10 numbers; contact support for more. This endpoint and `DELETE` are limited to 10 requests per minute per API key.
- [List all workflows](https://doc.voicedock.ai/docs/api/workflows/listWorkflows): Retrieve all workflows in your organization. The list view summarizes each graph (entry node, node and edge counts); request a single workflow to get the full definition.
- [Create a workflow](https://doc.voicedock.ai/docs/api/workflows/createWorkflow): Create a workflow. The definition is validated on write and anything invalid comes back as HTTP 400 with a `details` array listing every problem. Two kinds of check run there. The graph itself: unknown node references, unreachable nodes, missing edge descriptions, a transfer without an E.164 destination, and so on. And the values in the per-node config blocks, against the platform catalog: an unknown `provider` or `model` in `llm_config`, `tts_config` or `stt_config`, an unknown `stt_config.language`, an unknown `tts_config.voice_id` for a provider whose voices the catalog enumerates, a realtime provider in `llm_config` (realtime models cannot be set per node), and a `speech_config` block on a node (speech settings belong to the assistant).

What write-time validation cannot judge is the assistant, because a workflow is stored on its own and is not bound to one until you attach it to a number. Everything that depends on the assistant is therefore checked at call start instead, where it fails closed and rejects before pickup rather than mid-call: per-node model overrides and `tts_config` / `stt_config` on a realtime assistant, a `voice` that does not belong to the provider of the assistant on the number, and a config block without a `provider`. A `201` says the definition is sound, not that every override suits the assistant that will end up running it. Attach it to a phone number with `PATCH /numbers/{id}`.
- [Get a workflow](https://doc.voicedock.ai/docs/api/workflows/getWorkflow): Retrieve a specific workflow with its full definition.
- [Update a workflow](https://doc.voicedock.ai/docs/api/workflows/updateWorkflow): Update a workflow's name, definition or active state. A new definition replaces the old one entirely and is validated the same way as on create. Changes apply to the next call; calls already in progress finish on the definition they started with.
- [Delete a workflow](https://doc.voicedock.ai/docs/api/workflows/deleteWorkflow): Delete a workflow. Deletion is refused with HTTP 409 while phone numbers still run this workflow - detach them first with `PATCH /numbers/{id}` and `workflow_id: null` - so live numbers never change behaviour as a side effect.
- [List calls](https://doc.voicedock.ai/docs/api/calls/listCalls): Retrieve call history with optional filtering by status and date range. Returns complete call data including transcripts, analysis results, and metadata.
- [Get call by ID](https://doc.voicedock.ai/docs/api/calls/getCall): Retrieve complete details for a specific call including transcript, analysis results, and all metadata.
- [Initiate outbound call](https://doc.voicedock.ai/docs/api/calls/createOutboundCall): Initiate an outbound call from an AI assistant to a destination phone number.

**Phone Number Selection (Important for Resellers):**

You can specify which phone number to call from using the `number_id` parameter. This is **highly recommended** for:
- **Resellers**: Ensure calls are made from numbers dedicated to specific clients
- **Branding**: Always use the same caller ID for recognition
- **Compliance**: Meet legal requirements for specific numbers
- **Local presence**: Use local numbers for better answer rates

If `number_id` is not provided, the system will automatically select an available number from your organization's pool, which may not be appropriate for reseller scenarios where numbers are client-specific.

**Three Usage Modes:**

1. **Reference Mode** (`assistant_id`)
   - Reference an existing assistant from your dashboard
   - Uses the assistant's pre-configured settings
   - Simplest option for standard calls

2. **Transient Mode** (`assistant`)
   - Create a one-time assistant configuration without saving
   - Full control over STT/LLM/TTS configuration
   - Perfect for personalized or context-specific calls

3. **Hybrid Mode** (`assistant_id` + `assistant_override`)
   - Reference a saved assistant as the base
   - Override specific fields (e.g., first_message, llm_config.messages)
   - Best for personalization while keeping base config

**⚠️ Deprecated:** `agent_id`, `agent`, and `agent_config` are deprecated. Use `assistant_id`, `assistant`, and `assistant_override` instead.

**Use Cases:**
- Appointment reminders with personalized greetings
- Customer follow-ups with dynamic context
- Survey calls with specific question flows
- Delivery notifications
- Payment reminders with account-specific details

**Configuration Notes:**

- Whether `stt_config` and `tts_config` are needed follows from `llm_config.provider`. The assistant schema below carries that as a condition, generated from the platform catalog; this text deliberately does not repeat the provider names, because a second list here would go stale the moment a provider is added.
- With a realtime (speech-to-speech) provider the model handles transcription and speech itself: both blocks are unnecessary, are ignored when sent, and the voice goes in `llm_config.voice`.
- Every other provider runs the orchestrated STT -> LLM -> TTS pipeline and needs both blocks.
- The call will be initiated immediately and the response will include a `call_id` to track progress

**Response Time:** Your call will typically connect within 2-5 seconds.
- [Send control command to active call](https://doc.voicedock.ai/docs/api/call-control/controlCall): Send real-time commands to an active call. The call must be in "in-progress" status.

**⚠️ IMPORTANT: xAI Realtime Model Limitations**

Call control has **significant limitations** when using xAI Realtime (grok-realtime-v1) due to its speech-to-speech architecture:

- ❌ `inject-context`: Limited effectiveness - context may not influence responses reliably
- ❌ `say`: Does not work reliably - commands often timeout or fail to trigger speech
- ✅ `end-call`: Works reliably
- ⚠️ `transfer`: Partial support - announcement may not work, but transfer executes

**Why the limitations?**
xAI Realtime is an end-to-end audio model that processes speech directly without intermediate text. It expects continuous audio input and cannot reliably respond to text-based control commands mid-conversation.

**Recommendation:**
If you need full call control support (`inject-context`, `say`, `transfer` with announcements), use the traditional pipeline:
- **Provider**: `openai` with `gpt-4o` or `gpt-4o-mini`
- **STT**: Deepgram (`nova-3-general`)
- **TTS**: ElevenLabs or OpenAI TTS
- **Result**: All control commands work reliably

**Command Types:**
- `inject-context`: Silently add information to the agent's context (traditional models only)
- `say`: Make the agent speak specific text (traditional models only)
- `end-call`: End the call with an optional final message (works with all models)
- `transfer`: Transfer the call to another destination (partial xAI Realtime support)

**Use Cases:**
- SMS verification: Inject received codes into the conversation
- CRM integration: Add customer context mid-call
- Human escalation: Transfer to a live agent
- Emergency end: Gracefully terminate problematic calls
- [List all campaigns](https://doc.voicedock.ai/docs/api/campaigns/listCampaigns): Retrieve all outbound campaigns in your organization.
- [Create a campaign](https://doc.voicedock.ai/docs/api/campaigns/createCampaign): Create a new outbound calling campaign with leads and schedule.
- [Get a campaign](https://doc.voicedock.ai/docs/api/campaigns/getCampaign): Retrieve a specific campaign by ID.
- [Update a campaign](https://doc.voicedock.ai/docs/api/campaigns/updateCampaign): Update campaign settings or status. Set status to `scheduled` to start calling.
- [Delete a campaign](https://doc.voicedock.ai/docs/api/campaigns/deleteCampaign): Delete a campaign and all its leads.
- [List campaign leads](https://doc.voicedock.ai/docs/api/campaigns/listCampaignLeads): Retrieve all leads in a campaign.
- [Add a lead](https://doc.voicedock.ai/docs/api/campaigns/addCampaignLead): Add a new lead to a campaign.
- [Remove a lead](https://doc.voicedock.ai/docs/api/campaigns/removeCampaignLead): Remove a lead from a campaign.
- [List chat messages (deprecated)](https://doc.voicedock.ai/docs/api/chats/listChatMessages): **Deprecated — these endpoints will be removed on or after 5 January 2027.**

Chats stores messages and nothing else: it does not generate a reply, it does not run your assistant, and no other part of the platform reads what you put here. The reply you store is one your own application already produced, so this is a database you have to authenticate to rather than a capability you gain.

Keep your messages in your own storage instead. To give a voice call the history of an earlier chat, return it as system context in your response to the assistant-request webhook, which already reaches you on every inbound call.

List chat messages for a contact, newest first. Use this for dashboards or manual inspection; use `/chats/context` when feeding history to an LLM or voice agent.
- [Append a chat message (deprecated)](https://doc.voicedock.ai/docs/api/chats/createChatMessage): **Deprecated — these endpoints will be removed on or after 5 January 2027.**

Chats stores messages and nothing else: it does not generate a reply, it does not run your assistant, and no other part of the platform reads what you put here. The reply you store is one your own application already produced, so this is a database you have to authenticate to rather than a capability you gain.

Keep your messages in your own storage instead. To give a voice call the history of an earlier chat, return it as system context in your response to the assistant-request webhook, which already reaches you on every inbound call.

Store a single chat message for a contact.

Chats are a lightweight, developer-first storage primitive. VoiceDock keeps the
messages — your application keeps the LLM logic, tools, and channel wiring
(Meta Cloud API, widget, SMS gateway, etc.).

Messages are append-only; update by inserting a new message and delete
individually via `DELETE /chats/{id}`.
- [Delete a chat message (deprecated)](https://doc.voicedock.ai/docs/api/chats/deleteChatMessage): **Deprecated — these endpoints will be removed on or after 5 January 2027.**

Chats stores messages and nothing else: it does not generate a reply, it does not run your assistant, and no other part of the platform reads what you put here. The reply you store is one your own application already produced, so this is a database you have to authenticate to rather than a capability you gain.

Keep your messages in your own storage instead. To give a voice call the history of an earlier chat, return it as system context in your response to the assistant-request webhook, which already reaches you on every inbound call.

Permanently delete a single chat message. Scoped to your organization.
- [Get conversation context for a contact (deprecated)](https://doc.voicedock.ai/docs/api/chats/getChatContext): **Deprecated — these endpoints will be removed on or after 5 January 2027.**

Chats stores messages and nothing else: it does not generate a reply, it does not run your assistant, and no other part of the platform reads what you put here. The reply you store is one your own application already produced, so this is a database you have to authenticate to rather than a capability you gain.

Keep your messages in your own storage instead. To give a voice call the history of an earlier chat, return it as system context in your response to the assistant-request webhook, which already reaches you on every inbound call.

Return the last N messages for a contact in chronological order (oldest → newest).

The response contains two views:
- `messages`: raw message rows ready to map into an LLM chat array.
- `formatted`: a single string (`ROLE: content` per line) convenient to append to a voice agent's system prompt for cross-channel continuity.
- [List all tool templates](https://doc.voicedock.ai/docs/api/tool-templates/listToolTemplates): Retrieve all tool templates in your organization.
- [Create a new tool template](https://doc.voicedock.ai/docs/api/tool-templates/createToolTemplate): Create a new reusable tool template. Tools can be of type 'function' (custom webhook), 'end_call' (built-in), or 'transfer_call' (built-in). The type is snake_case only; 'endCall' and 'transferCall' are rejected with a 400.
- [Get a tool template](https://doc.voicedock.ai/docs/api/tool-templates/getToolTemplate): Retrieve a specific tool template by ID.
- [Update a tool template](https://doc.voicedock.ai/docs/api/tool-templates/updateToolTemplate): Update an existing tool template. Only provided fields will be updated.
- [Delete a tool template](https://doc.voicedock.ai/docs/api/tool-templates/deleteToolTemplate): Delete a tool template. Note that agents using this tool will continue to work as tools are stored as objects in the agent configuration, not as references.
- [List MCP servers](https://doc.voicedock.ai/docs/api/mcp-servers/listMcpServers): Retrieve the MCP servers of your organization. Header values are never returned.
- [Add an MCP server](https://doc.voicedock.ai/docs/api/mcp-servers/createMcpServer): Add an MCP server that your assistants can use during a call. Authenticate with the headers the server expects, such as an API key or a bearer token you obtained from its provider; the platform stores them encrypted and sends them with every request. Then attach the server to an assistant with a tool of type `mcp` in `llm_config.tools`.

The URL must use `https://` and resolve to a public address.
- [Get an MCP server](https://doc.voicedock.ai/docs/api/mcp-servers/getMcpServer): Retrieve one MCP server. Header values are never returned; `header_names` shows which are set.
- [Update an MCP server](https://doc.voicedock.ai/docs/api/mcp-servers/updateMcpServer): Change an MCP server. Only the fields you send are changed. `headers` replaces all stored headers: leave it out to keep them, send `{}` to remove them. Use this to renew a token that expires. When `url` points to a different host (scheme, host or port) than before, send `headers` in the same request, `{}` if the new host needs none: stored headers never go to a new host, and without them the request is refused with 400. The change applies from the next call; calls in progress keep the connection they opened.
- [Delete an MCP server](https://doc.voicedock.ai/docs/api/mcp-servers/deleteMcpServer): Delete an MCP server and its stored headers. Deletion is refused with HTTP 409 while an assistant still uses the server, so no assistant loses a tool as a side effect. Remove the `mcp` tool from those assistants first.
- [Test an MCP server](https://doc.voicedock.ai/docs/api/mcp-servers/testMcpServer): Connect to the MCP server from the platform and list its tools, with the stored headers. Use it after adding a server, and to see the exact tool names for `allowed_tools`.

To test a token you only pass per call, send it in `headers`: those are merged over the stored headers for this test only and are not stored.
- [List analysis templates](https://doc.voicedock.ai/docs/api/analysis-templates/listAnalysisTemplates): Get all analysis templates for your organization
- [Create analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/createAnalysisTemplate): Create a new analysis template for your organization
- [Get analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/getAnalysisTemplate): Retrieve a specific analysis template by ID
- [Update analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/updateAnalysisTemplate): Update an existing analysis template
- [Delete analysis template](https://doc.voicedock.ai/docs/api/analysis-templates/deleteAnalysisTemplate): Delete an analysis template
- [Get the Arena catalog](https://doc.voicedock.ai/docs/api/arena/getArenaCatalog): Personas, audio profiles, timeline events, channels, criterion kinds and metrics you can use in a test case.
- [List test suites](https://doc.voicedock.ai/docs/api/arena/listArenaSuites): Get all test suites of your organization.
- [Create test suite](https://doc.voicedock.ai/docs/api/arena/createArenaSuite): A suite tests one assistant on one of your phone numbers. The test caller calls from another number of yours, over your own SIP trunk; a managed number cannot place calls.
- [Get test suite](https://doc.voicedock.ai/docs/api/arena/getArenaSuite): A test suite with its current test cases.
- [Delete test suite](https://doc.voicedock.ai/docs/api/arena/deleteArenaSuite): Deletes the suite with its cases and runs. A suite with a run in progress cannot be deleted.
- [List test cases](https://doc.voicedock.ai/docs/api/arena/listArenaCases): Test cases of a suite. Retired versions are left out unless include_retired is true.
- [Save test case](https://doc.voicedock.ai/docs/api/arena/saveArenaCase): Saving with an existing key creates a new version; a version used in a run never changes. Every tool of the assistant needs a choice in tool_mode: live, mock or fault. There is no default. facts, each tool response and each criterion are at most 8 KB as JSON, the whole case at most 64 KB. source_call_ids must be calls of your organization.
- [Get test case](https://doc.voicedock.ai/docs/api/arena/getArenaCase): One version of a test case.
- [Activate or retire test case](https://doc.voicedock.ai/docs/api/arena/updateArenaCaseStatus): Only the status changes. Activating a version retires the active version with the same key.
- [List runs](https://doc.voicedock.ai/docs/api/arena/listArenaRuns): Runs of a suite, newest first.
- [Start run](https://doc.voicedock.ai/docs/api/arena/startArenaRun): Calls each active test case (or those in case_ids) repeats times. Test calls are real calls and are billed as such on both legs. The cost is estimated up front, with every call at its full max_duration_s, and the run is refused if your balance does not cover the estimate.
- [Get run](https://doc.voicedock.ai/docs/api/arena/getArenaRun): A run with its attempts, verdicts and metrics. A void attempt does not count and always carries a reason.
- [Cancel run](https://doc.voicedock.ai/docs/api/arena/cancelArenaRun): Attempts still in the queue stop; a call already in progress is finished.
- [Get routine](https://doc.voicedock.ai/docs/api/arena/getArenaSchedule): The routine of a suite, or null when it has none. Includes what its runs cost this month.
- [Delete routine](https://doc.voicedock.ai/docs/api/arena/deleteArenaSchedule): Removes the routine of a suite. Its runs and results stay.
- [Save routine](https://doc.voicedock.ai/docs/api/arena/saveArenaSchedule): Creates or updates the routine of a suite. A routine is off until you enable it and always has a monthly budget: at the budget it pauses and sends arena.schedule.paused. Saving it enabled again resumes it. It runs on its schedule, and optionally after a change to the assistant's configuration or a platform release. PUT replaces the whole routine: every field you leave out takes its default (enabled: false, cadence: daily, weekday: null, window_start: 02:00, window_end: 05:00, timezone: Europe/Amsterdam, repeats: 3, webhook_url: null, on_config_change: false, on_platform_release: false, notify_email: true). Send the full routine each time, for example what GET returned with your changes.
- [Get trend](https://doc.voicedock.ai/docs/api/arena/getArenaTrend): Pass rates per case and criterion over the latest runs, each with the passed and judged attempts and a 95% Wilson interval, plus the open regressions. A regression is a drop of at least 10 percentage points against the runs of the previous 14 days that is significant (Fisher exact, p < 0.05), or a single failure of a critical criterion.
- [List SIP trunks](https://doc.voicedock.ai/docs/api/sip-trunks/listSipTrunks): Retrieve all SIP trunks configured for your organization's call transfers.
- [Create a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/createSipTrunk): Create a new SIP trunk for call transfers. Passwords are stored securely in Vault.
- [Get a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/getSipTrunk): Retrieve a specific SIP trunk by ID.
- [Delete a SIP trunk](https://doc.voicedock.ai/docs/api/sip-trunks/deleteSipTrunk): Delete a SIP trunk. Any numbers using this trunk for transfers will have their transfer_trunk_id set to null.
- [Get BYOK configurations](https://doc.voicedock.ai/docs/api/byok/getBYOKConfigs): Retrieve all Bring Your Own Key configurations for your organization.
- [Add BYOK configuration](https://doc.voicedock.ai/docs/api/byok/addBYOKConfig): Add or update a Bring Your Own Key configuration. The API key is securely stored in Supabase Vault and only the vault secret ID is stored in the database.
- [Delete BYOK configuration](https://doc.voicedock.ai/docs/api/byok/deleteBYOKConfig): Remove a Bring Your Own Key configuration. This will delete the secret from Vault and remove the reference from the database.
- [Save BYOK provider configuration](https://doc.voicedock.ai/docs/api/byok/saveBYOKProviderConfig): Store the non-secret configuration for a provider you have brought your own key for, such as the selected model or region. The API key itself is not set here — use POST /byok for that, which stores it in Vault.
- [List available voices (deprecated)](https://doc.voicedock.ai/docs/api/voices/listVoices): **Deprecated — this endpoint returns an empty list and will be removed in a later release; the removal will be announced in the changelog.**

It listed the voices of the former `local` text-to-speech provider, which has been removed from the platform. The voices you can use are set per provider on the assistant, and none of them come from this endpoint:

- **VoiceDock voice (beta).** Set `tts_config.provider: voicedock`, model `voicedock-1` and voice `voicedock`.
- **ElevenLabs.** Any voice from your ElevenLabs voice library, as `tts_config.voice_id`.
- **Inworld, Google and xAI text-to-speech.** The voices per provider are listed in the `tts_config` reference on the Assistants page.
- **Realtime models** (Gemini Live, Grok Realtime, GPT-Live). Set the voice with `llm_config.voice`; the voices per provider are listed in the `llm_config` reference.
- [Get your domain](https://doc.voicedock.ai/docs/api/domains/getDomain): Retrieve your organization's configured email domain from Resend. Requires a Resend API key to be configured via BYOK (Bring Your Own Key). Returns null if no domain is configured.
- [Add a domain](https://doc.voicedock.ai/docs/api/domains/createDomain): Create a custom email domain in Resend for sending notifications from your organization. Requires a Resend API key configured via BYOK. You can only have one domain configured per organization.
- [Delete your domain](https://doc.voicedock.ai/docs/api/domains/deleteDomain): Remove your organization's configured email domain from both the database and Resend.
- [List available Resend domains](https://doc.voicedock.ai/docs/api/domains/listResendDomains): Fetch all domains configured in your Resend account. Use this to see which domains you can select for your organization's email notifications. Requires a Resend API key configured via BYOK.
- [Select and sync a Resend domain](https://doc.voicedock.ai/docs/api/domains/syncResendDomain): Select a domain from your Resend account to use for your organization's email notifications. This syncs the domain configuration to your organization.
- [Verify domain DNS records](https://doc.voicedock.ai/docs/api/domains/verifyDomain): Trigger domain verification in Resend to check if DNS records are correctly configured. This updates the domain status based on Resend's verification results.
- [Refresh domain status](https://doc.voicedock.ai/docs/api/domains/refreshDomain): Fetch the latest domain status from Resend and update your local configuration. Use this to check if verification has completed or if any records need attention.
- [Get usage logs](https://doc.voicedock.ai/docs/api/usage/getUsage): Retrieve your organization's usage logs with billing information and optional date filtering.
- [Get organization information](https://doc.voicedock.ai/docs/api/organization/getOrganization): Retrieve your organization details including balance, usage statistics, and resource counts. Use `include_children=true` to also list child organizations (for agencies).
- [Create organization](https://doc.voicedock.ai/docs/api/organization/createOrganization): Create a new organization. If `parent_org_id` is provided, creates a child organization that bills to the parent (for whitelabel use cases). The API key for the new organization is only returned once at creation time.
- [Update organization retention](https://doc.voicedock.ai/docs/api/organization/updateOrganization): Set how long your organization's calls are kept. Content covers the transcript, summary, analysis result and recording; metadata covers the caller's phone number, the campaign link and the call events. Content cannot be kept longer than metadata.

Shortening a period destroys data: the nightly cleanup erases everything older than the new period, and that cannot be undone. Both fields are required, because they are validated against each other.

Unlimited retention is a contractual exception and is not available through this endpoint. See [Privacy & compliance](/docs/features/privacy-compliance#retention).
- [Get organization information (deprecated)](https://doc.voicedock.ai/docs/api/organization/getOrganizationLegacy): **Deprecated:** Use `/organizations` instead. Retrieve your organization details including balance, usage statistics, and resource counts.
- [Health check](https://doc.voicedock.ai/docs/api/system/getHealth): Returns the current health status of the API and its dependencies. No authentication required.
- [Dynamic assistant configuration webhook](https://doc.voicedock.ai/docs/api/webhooks/assistantRequestWebhook): Called **BEFORE** an inbound call is answered, allowing you to:
- Dynamically configure the assistant based on caller information
- Personalize the greeting message
- Override STT/LLM/TTS configuration
- Set call-specific analysis plans
- Reject calls based on business logic (e.g., outside business hours)
- Pass custom metadata that will be echoed in all subsequent webhook events

⚠️ **Important:** Your endpoint must respond within **5 seconds** or the call will proceed with default agent configuration.

### Response Modes

**1. Default mode** - Use saved agent config:
```json
{}
```

**2. Transient agent** - Full config override:
```json
{
  "assistant": {
    "first_message": "Hello John!",
    "tts_config": {"voice_id": "..."},
    "metadata": {"crm_id": "12345"}
  }
}
```

**3. Hybrid agent** - Reference saved agent + overrides:
```json
{
  "assistant_id": "uuid-of-saved-agent",
  "assistant_override": {
    "tts_config": {"voice_id": "female-voice"},
    "first_message": "Hello John!",
    "metadata": {"crm_id": "12345"}
  }
}
```

The hybrid mode uses **shallow merge**: each top-level key in `assistant_override` completely replaces that config block from the saved agent.

### Custom Metadata

Any fields you add to the assistant config (like `metadata`) will be echoed back in all subsequent webhook events (`status-update`, `tool-calls`, `end-of-call-report`). This is useful for passing CRM IDs, campaign info, or any context you need.
- [Tool/Function Call](https://doc.voicedock.ai/docs/api/webhooks/toolCallsWebhook): Called when the AI needs to execute a tool/function during the conversation.

**Sync tools:** Must respond within **10 seconds** with the result.
**Async tools:** Respond immediately with `200 OK` (fire-and-forget).

Tools are defined in `llm_config.tools[]` with optional per-tool URL override.

### Assistant Object

The payload includes the full `assistant` object containing:
- All resolved configuration (after any overrides from `assistant-request`)
- Any custom `metadata` you passed in the `assistant-request` response

### Response Formats

Multiple response formats are supported:

1. **Object format** (recommended):
```json
{"results": [{"tool_call_id": "tool_abc123", "result": {"name": "Jan"}}]}
```

2. **Simple format**:
```json
{"result": {"name": "Jan"}}
```

3. **Direct format** (your data directly):
```json
{"name": "Jan"}
```

4. **Error format**:
```json
{"error": "Contact not found"}
```
- [Call Status Update](https://doc.voicedock.ai/docs/api/webhooks/statusUpdateWebhook): Called when the call status changes. Use this to track call lifecycle.

**Statuses:**
- `in-progress`: Call connected, conversation started
- `ended`: Call ended normally (customer hung up)
- `ended-with-error`: Call ended due to an error

### Assistant Object

The payload includes the full `assistant` object containing:
- All resolved configuration (after any overrides from `assistant-request`)
- Any custom `metadata` you passed in the `assistant-request` response

The response body is ignored.
- [End of Call Report](https://doc.voicedock.ai/docs/api/webhooks/endOfCallReportWebhook): Called after the call ends with a summary and optional structured analysis.

This is the most commonly used webhook for integrating call data into CRM systems.

**Payload includes:**
- Call duration in seconds
- AI-generated call summary
- Full conversation transcript (messages array)
- Structured analysis result (if `analysis_plan` was configured on the agent)
- Full assistant configuration including any custom metadata
- Recording URL (if recording is enabled)

### Assistant Object

The payload includes the full `assistant` object containing:
- All resolved configuration (after any overrides from `assistant-request`)
- Any custom `metadata` you passed in the `assistant-request` response

This is especially useful for correlating call reports with your CRM records using the metadata you passed during `assistant-request`.

The response body is ignored.