# Vocobase API

> Voice AI Agent Platform — Partner API Documentation

## Docs

- [Link documents to an agent](https://docs.vocobase.com/api-reference/agent-documents/link-documents-to-an-agent.md): Links one or more documents to an agent for knowledge base integration. Documents must be in `ready` status. Duplicate links are silently skipped (idempotent). Maximum 20 document IDs per request, 100 total linked documents per agent. Indexing starts for newly linked documents.
- [List linked documents](https://docs.vocobase.com/api-reference/agent-documents/list-linked-documents.md): Returns all documents linked to an agent, including their sync status.
- [Unlink a document from an agent](https://docs.vocobase.com/api-reference/agent-documents/unlink-a-document-from-an-agent.md): Removes the association between a document and an agent. The document itself is not deleted. Knowledge-base cleanup is handled asynchronously.
- [Create an agent](https://docs.vocobase.com/api-reference/agents/create-an-agent.md): Creates a new voice AI agent. The `voice_id` must be a voice ID from the voice catalog (see `GET /agent/voices`). Agent names must be unique per partner.
- [Delete an agent](https://docs.vocobase.com/api-reference/agents/delete-an-agent.md): Soft-deletes an agent and removes all linked document associations. Related knowledge-base cleanup is handled asynchronously.
- [Get an agent](https://docs.vocobase.com/api-reference/agents/get-an-agent.md): Returns a single agent by ID.
- [List agents](https://docs.vocobase.com/api-reference/agents/list-agents.md): Returns a paginated list of the partner's agents, ordered by creation date (newest first). Deleted agents are excluded.
- [List attached dictionaries](https://docs.vocobase.com/api-reference/agents/list-attached-dictionaries.md): Returns all speech-recognition dictionaries currently attached to the agent. The summary shape does not include `description` or `terms`.
- [Replace the agent's attached dictionaries](https://docs.vocobase.com/api-reference/agents/replace-the-agents-attached-dictionaries.md): Idempotent set-replace: overwrites the agent's entire dictionary set with `dictionary_ids`. Duplicate ids are deduped silently. Every id must exist and belong to the calling partner, else the whole request fails with `VALIDATION_ERROR`. The combined `char_count` across the resulting set must be at m…
- [Update an agent](https://docs.vocobase.com/api-reference/agents/update-an-agent.md): Updates one or more agent fields. Only provided fields are changed. At least one field must be provided.
- [Finalize an uploaded asset](https://docs.vocobase.com/api-reference/background-audio/finalize-an-uploaded-asset.md): Step 3 of the upload: Vocobase validates the just-uploaded WAV file and either marks the asset `READY` (with detected `duration_secs`, `sample_rate`, `channels`) or `FAILED` with a human-readable error.
- [List background audio assets](https://docs.vocobase.com/api-reference/background-audio/list-background-audio-assets.md): Returns every background-audio asset visible to this partner — both platform-curated (`is_platform: true`) and the partner's own uploads. Each row includes a 15-minute presigned `preview_url` for in-browser playback.
- [Mint a presigned upload URL](https://docs.vocobase.com/api-reference/background-audio/mint-a-presigned-upload-url.md): Step 1 of the two-step upload: returns a 15-minute presigned PUT URL plus the `id` of a new upload. Then PUT the WAV bytes directly to `upload_url` with `Content-Type: audio/wav`, then call `POST /agent/background-audio/{id}/finalize`.
- [Soft-delete a background-audio asset](https://docs.vocobase.com/api-reference/background-audio/soft-delete-a-background-audio-asset.md): Soft-deletes the asset and detaches it from any agents currently using it (`background_audio_id` cleared).
- [Dismiss stale calls](https://docs.vocobase.com/api-reference/calls/dismiss-stale-calls.md): Cancels all calls in `pending` or `ringing` status for the authenticated partner. Useful for cleaning up calls that did not connect.
- [Get a fresh recording URL](https://docs.vocobase.com/api-reference/calls/get-a-fresh-recording-url.md): Mints a freshly signed download URL for the call's recording, valid for 7 days. Use this when the `recording_url` returned by `GET /calls/{id}` or by the `session.completed` webhook has expired.
- [Get call details](https://docs.vocobase.com/api-reference/calls/get-call-details.md): Returns full call details including the associated session with transcript, credits used, and a temporary recording download URL (if recording was enabled). The `recording_url` is valid for 7 days; use `GET /calls/{id}/recording-url` to mint a fresh URL after expiry.
- [Get current call concurrency](https://docs.vocobase.com/api-reference/calls/get-current-call-concurrency.md): Returns the authenticated partner account's current phone-call capacity. The limit is resolved as: partner override (`maxConcurrentCalls > 0`) caps the account at that value; partner `maxConcurrentCalls = 0` means unlimited (no cap), in which case `limit` and `remaining` are `null` and `limit_source…
- [List calls](https://docs.vocobase.com/api-reference/calls/list-calls.md): Returns a paginated list of calls, ordered by start time (newest first). Optionally filter by status. `status` is the call lifecycle/carrier state; use `disposition` on each call for the final outcome such as `voicemail`, `busy`, or `no_answer`.
- [Run post-call extraction (Test Analysis / replay)](https://docs.vocobase.com/api-reference/calls/run-post-call-extraction-test-analysis-replay.md): Re-runs post-call extraction against an existing session's stored transcript using the agent's CURRENT `extraction_config`. Useful after editing the config to backfill old sessions, or to test a config against real conversation data.
- [Start an outbound call](https://docs.vocobase.com/api-reference/calls/start-an-outbound-call.md): Initiates an outbound phone call via MCube, Twilio, Exotel, Plivo, Vobiz, or SIP. Requires sufficient credits and available call concurrency; use `GET /calls/concurrency` to inspect current capacity before starting a call. The provider you pass must appear in the partner's `allowed_telephony_provide…
- [Transfer a live call to a human](https://docs.vocobase.com/api-reference/calls/transfer-a-live-call-to-a-human.md): Transfers an active in-progress call to a human phone number via Plivo. The bot announces the transfer, then Plivo bridges the caller directly to the destination number. The call's `session.completed` webhook will include transfer metadata when the full call ends.
- [Add contacts to a campaign](https://docs.vocobase.com/api-reference/campaigns/add-contacts-to-a-campaign.md): Bulk-adds contacts to a campaign. The campaign must be in `draft` status. Up to 10,000 contacts per request; duplicates (same phone) are silently skipped. Existing contacts (by phone) are reused -- only new phones create new `Contact` rows.
- [Create a campaign](https://docs.vocobase.com/api-reference/campaigns/create-a-campaign.md): Creates a new campaign in `draft` status. Add contacts with `POST /campaigns/{id}/contacts`, then start the run with `POST /campaigns/{id}/start`.
- [Get a campaign](https://docs.vocobase.com/api-reference/campaigns/get-a-campaign.md): Fetches a campaign by ID.
- [Get campaign progress stats](https://docs.vocobase.com/api-reference/campaigns/get-campaign-progress-stats.md): Returns contact counts grouped by status, average call duration, and total credits consumed.
- [List campaigns](https://docs.vocobase.com/api-reference/campaigns/list-campaigns.md): Returns all campaigns created via the partner API, newest first.
- [Pause a running campaign](https://docs.vocobase.com/api-reference/campaigns/pause-a-running-campaign.md): Pauses a `running` campaign. In-flight calls finish; new calls are not dispatched until the campaign resumes.
- [Resume a paused campaign](https://docs.vocobase.com/api-reference/campaigns/resume-a-paused-campaign.md): Resumes a `paused` or `credit_exhausted` campaign. If resuming from `credit_exhausted`, the caller must have restored a minimum credit balance.
- [Start a campaign](https://docs.vocobase.com/api-reference/campaigns/start-a-campaign.md): Transitions the campaign from `draft` to `running`. Requires at least one contact and a minimum credit balance (0.3 display credits = 30 seconds at 1 credit/minute). The provider must still be in `allowed_telephony_providers`.
- [Stop (cancel) a campaign](https://docs.vocobase.com/api-reference/campaigns/stop-cancel-a-campaign.md): Cancels a `running`, `paused`, or `credit_exhausted` campaign. All queued contacts are marked `skipped`. This action is terminal -- cancelled campaigns cannot be restarted.
- [Create a webhook endpoint](https://docs.vocobase.com/api-reference/config/create-a-webhook-endpoint.md): Creates a labeled webhook endpoint. Each enabled endpoint receives the same webhook events and signs requests with its own secret. The secret is returned once in this response and cannot be read again.
- [Delete a webhook endpoint](https://docs.vocobase.com/api-reference/config/delete-a-webhook-endpoint.md): Deletes a webhook endpoint. Delivery attempts that were already created may still use the previous URL and secret, but the deleted endpoint stops receiving new events.
- [Get partner configuration](https://docs.vocobase.com/api-reference/config/get-partner-configuration.md): Returns the current partner configuration including webhook endpoints, telephony setup, agent limits, and allowed voices/languages. Sensitive values are masked.
- [List webhook endpoints](https://docs.vocobase.com/api-reference/config/list-webhook-endpoints.md): Lists all configured webhook endpoints for the authenticated partner. Secrets are never returned.
- [Rotate a webhook endpoint secret](https://docs.vocobase.com/api-reference/config/rotate-a-webhook-endpoint-secret.md): Generates a new signing secret for the endpoint. The new secret is returned once. Delivery attempts that were already created may still use the previous secret.
- [Set or update Exotel credentials](https://docs.vocobase.com/api-reference/config/set-or-update-exotel-credentials.md): Stores encrypted Exotel credentials for outbound calling. All six fields are required. The `caller_id` must be an E.164 phone number that Exotel has provisioned for your account.
- [Set or update MCube credentials](https://docs.vocobase.com/api-reference/config/set-or-update-mcube-credentials.md): Stores encrypted MCube JWT token and executive number for outbound calling.
- [Set or update Plivo credentials](https://docs.vocobase.com/api-reference/config/set-or-update-plivo-credentials.md): Stores encrypted Plivo credentials for outbound calling. All three fields are required. The `from_number` must be an E.164 phone number that Plivo has provisioned for your account.
- [Set or update the legacy default webhook URL](https://docs.vocobase.com/api-reference/config/set-or-update-the-legacy-default-webhook-url.md): Legacy compatibility endpoint. Creates or replaces the reserved `default` webhook endpoint used by older integrations. A new webhook secret is generated on each call. New integrations should use `POST /config/webhooks` to create labeled endpoints.
- [Set or update Twilio credentials](https://docs.vocobase.com/api-reference/config/set-or-update-twilio-credentials.md): Stores encrypted Twilio credentials for outbound calling. All three fields are required.
- [Set or update Vobiz credentials](https://docs.vocobase.com/api-reference/config/set-or-update-vobiz-credentials.md): Stores encrypted Vobiz credentials for outbound calling. All three fields are required. The `from_number` must be an E.164 phone number that Vobiz has provisioned for your account.
- [Update a webhook endpoint](https://docs.vocobase.com/api-reference/config/update-a-webhook-endpoint.md): Updates an endpoint's label, URL, or enabled state. Disabled endpoints stop receiving new webhook events.
- [Update partner display name](https://docs.vocobase.com/api-reference/config/update-partner-display-name.md): Changes the partner display name shown in the dashboard and API responses.
- [Create a dictionary](https://docs.vocobase.com/api-reference/dictionaries/create-a-dictionary.md): Creates a new speech-recognition dictionary for the partner. Terms are normalized server-side: whitespace is trimmed, empty/whitespace-only entries are dropped, non-string entries are silently skipped, and the dedupe is case-insensitive but preserves first-occurrence casing. A blank `description` is…
- [Delete a dictionary](https://docs.vocobase.com/api-reference/dictionaries/delete-a-dictionary.md): Permanently deletes a dictionary and cascades the attachment rows. Detaches it from every agent it was attached to. No other data is touched.
- [Get a dictionary](https://docs.vocobase.com/api-reference/dictionaries/get-a-dictionary.md): Returns the full detail for a single dictionary, including the `terms` array.
- [List dictionaries](https://docs.vocobase.com/api-reference/dictionaries/list-dictionaries.md): Returns every speech-recognition dictionary owned by the partner, ordered by creation date (newest first). The summary shape does not include the `terms` array -- fetch a single dictionary to see them.
- [Update a dictionary](https://docs.vocobase.com/api-reference/dictionaries/update-a-dictionary.md): Updates any subset of `name`, `description`, or `terms`. Passing `terms` replaces the whole list -- there is no incremental add/remove. If the dictionary is attached to any agent and the new `char_count` would push that agent over 10,000 combined characters, the request fails with `DICTIONARY_CHAR_L…
- [Add a web link document](https://docs.vocobase.com/api-reference/documents/add-a-web-link-document.md): Creates a document from a URL. The URL content will be crawled and indexed when linked to an agent. The document is immediately `ready` (no upload step needed).
- [Confirm document upload](https://docs.vocobase.com/api-reference/documents/confirm-document-upload.md): Confirms that the file has been uploaded. Verifies the file exists and transitions the document status from `uploading` to `ready`. Must be called after uploading to the presigned URL.
- [Delete a document](https://docs.vocobase.com/api-reference/documents/delete-a-document.md): Permanently deletes a document, removes the stored file if applicable, and unlinks it from all agents. Knowledge-base cleanup is handled asynchronously.
- [Get a document](https://docs.vocobase.com/api-reference/documents/get-a-document.md): Returns a single document with a temporary download URL (for file documents) or the original URL (for web links), plus a list of linked agents with their sync status.
- [Get presigned upload URL](https://docs.vocobase.com/api-reference/documents/get-presigned-upload-url.md): Creates a document record and returns a presigned URL for uploading the file. After uploading, call `POST /documents/{id}/confirm` to finalize. The upload URL expires in 15 minutes.
- [List documents](https://docs.vocobase.com/api-reference/documents/list-documents.md): Returns a paginated list of all documents, ordered by creation date (newest first). Each document includes the number of agents it is linked to.
- [Update a document](https://docs.vocobase.com/api-reference/documents/update-a-document.md): Updates the document name and/or description. At least one field must be provided. Invalidates KB cache for all agents linked to this document.
- [Assign an agent to a DID](https://docs.vocobase.com/api-reference/phone-numbers/assign-an-agent-to-a-did.md): Updates a phone number's agent assignment, friendly name, or status. When `agent_id` changes for Plivo or Vobiz, Vocobase first updates the carrier Application binding and then updates the local record. If carrier sync fails, the local assignment is not committed.
- [Delete an imported phone number](https://docs.vocobase.com/api-reference/phone-numbers/delete-an-imported-phone-number.md): Deletes an imported DID from Vocobase. Plivo assigned numbers are best-effort detached from the Plivo Application before deletion. Default from-numbers cannot be deleted.
- [List imported phone numbers](https://docs.vocobase.com/api-reference/phone-numbers/list-imported-phone-numbers.md): Lists the partner's imported Plivo and Vobiz DIDs. Use the optional `provider` query to filter to one carrier. The returned phone number `id` is used by `PUT /phone-numbers/{id}` for agent assignment.
- [Re-apply carrier Application bindings](https://docs.vocobase.com/api-reference/phone-numbers/re-apply-carrier-application-bindings.md): Re-applies the Vocobase answer/status Application binding to every assigned DID for the requested provider. Use this after rotating credentials, editing carrier-side settings directly, or validating that all assigned DIDs point back to Vocobase.
- [Sync Plivo or Vobiz DIDs](https://docs.vocobase.com/api-reference/phone-numbers/sync-plivo-or-vobiz-dids.md): Imports DIDs into Vocobase for inbound routing. For Plivo, Vocobase pulls the inventory from Plivo REST using the partner's configured credentials. For Vobiz, pass an explicit `numbers` array because Vobiz inventory pull is not available. Vobiz uses `numbers`, not `phone_numbers`.
- [Create project](https://docs.vocobase.com/api-reference/projects/create-project.md): Creates a new project. Project names must be unique per partner.
- [Delete project](https://docs.vocobase.com/api-reference/projects/delete-project.md): Deletes a project. Cannot delete the default project or projects that still have agents.
- [Get project](https://docs.vocobase.com/api-reference/projects/get-project.md): Returns a single project by ID.
- [List projects](https://docs.vocobase.com/api-reference/projects/list-projects.md): Returns all projects for the authenticated partner, including agent counts.
- [Update project](https://docs.vocobase.com/api-reference/projects/update-project.md): Updates a project's name and/or description.
- [Get a session](https://docs.vocobase.com/api-reference/sessions/get-a-session.md): Returns the same fields delivered by the `session.completed` partner webhook (transcript, recording, extraction, variables, agent name, status, duration, credits). Polling fallback for partners that can't accept inbound webhooks. Mints a fresh presigned `recording_url` on every call (valid 7 days).…
- [Start a browser WebRTC session](https://docs.vocobase.com/api-reference/sessions/start-a-browser-webrtc-session.md): Creates a browser voice session and returns a room URL plus a one-time access token your browser uses to connect to the agent in real time.
- [List available voices](https://docs.vocobase.com/api-reference/voices/list-available-voices.md): Returns the voice catalog. Each voice has a tier (`va-1` or `va-1-pro`) that determines the per-minute rate at billing time. Pass the row's `id` as `voice_id` when creating or updating an agent.
- [Authentication](https://docs.vocobase.com/authentication.md): API key format, headers, rate limits, and error codes
- [B2B2B — Customer-Scoped Tool Connections](https://docs.vocobase.com/b2b2b-customers.md): Give each of your downstream customers their own isolated OAuth and API-key credentials for tools like Google Sheets, Slack, Cal.com, and Zendesk.
- [Call Duration & Background Audio](https://docs.vocobase.com/call-duration-and-background-audio.md): Cap how long any single call can run, and mix ambient audio under your agent's voice
- [Call Transfer & Behavior](https://docs.vocobase.com/call-transfer.md): Transfer live calls to human agents and configure end-call/transfer triggers
- [Billing (₹)](https://docs.vocobase.com/credits.md): How Vocobase bills voice and chat usage in Indian Rupees
- [Custom Functions](https://docs.vocobase.com/custom-functions.md): Give your voice agents the ability to call external APIs during conversations
- [Speech Recognition Dictionaries](https://docs.vocobase.com/dictionaries.md): Teach your agents the right spelling of product names, jargon, and proper nouns so the STT engine transcribes them correctly
- [Inbound Calls](https://docs.vocobase.com/inbound-calls.md): Configure your agents to receive and handle incoming phone calls
- [Vocobase Partner API](https://docs.vocobase.com/index.md): Build voice AI agents with the Vocobase API
- [Knowledge Base](https://docs.vocobase.com/knowledge-base.md): Upload documents and web links to give your agents contextual knowledge
- [Becoming a Partner](https://docs.vocobase.com/onboarding/becoming-a-partner.md): How to apply for Vocobase partner access and get your API key
- [Configuring Your Account](https://docs.vocobase.com/onboarding/configuring-your-account.md): Set up webhooks, telephony, and other partner configuration after approval
- [Post-call Extraction](https://docs.vocobase.com/post-call-extraction.md): Pull structured fields from completed call transcripts with an LLM-driven analyzer
- [Pre-call Variables](https://docs.vocobase.com/pre-call-variables.md): Template per-call data into your agent's prompt and greeting with `{{name}}` placeholders
- [Projects](https://docs.vocobase.com/projects.md): Organize your agents into projects
- [Quick Start](https://docs.vocobase.com/quickstart.md): Make your first API call in 5 minutes
- [Bring Your Own Phone](https://docs.vocobase.com/telephony/byop-setup.md): Use your own telephony provider with the Vocobase V2 API
- [Exotel Setup](https://docs.vocobase.com/telephony/exotel-setup.md): Configure Exotel for outbound voice calls
- [MCube Setup](https://docs.vocobase.com/telephony/mcube-setup.md): Configure MCube for outbound calling with the Vocobase API
- [Plivo Setup](https://docs.vocobase.com/telephony/plivo-setup.md): Configure Plivo for outbound calling with the Vocobase API
- [SIP (BYOP) Setup](https://docs.vocobase.com/telephony/sip-setup.md): Bring your own SIP carrier for inbound and outbound calling.
- [Twilio Setup](https://docs.vocobase.com/telephony/twilio-setup.md): Configure Twilio for outbound calling with the Vocobase API
- [Vobiz Setup](https://docs.vocobase.com/telephony/vobiz-setup.md): Configure Vobiz for outbound calling with the Vocobase API
- [Web Voice Testing](https://docs.vocobase.com/web-voice-testing.md): Test your voice agent from the browser using WebRTC
- [Webhook Error Handling](https://docs.vocobase.com/webhooks/error-handling.md): Retry policy, timeout behavior, and best practices for handling webhook deliveries
- [Webhook Payloads](https://docs.vocobase.com/webhooks/payloads.md): Reference for webhook event types and payload structure
- [Webhook Setup](https://docs.vocobase.com/webhooks/setup.md): Configure webhooks to receive call completion notifications

## OpenAPI Specs

- [openapi](https://docs.vocobase.com/openapi.json)