Create voice AI agent API

POST

agent

cURL

curl --request POST \
  --url https://api.bolna.ai/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_config": {
    "agent_name": "Alfred",
    "tasks": [
      {
        "task_config": {
          "hangup_after_silence": 10,
          "hangup_after_LLMCall": false,
          "incremental_delay": 400,
          "number_of_words_for_interruption": 2,
          "call_cancellation_prompt": null,
          "backchanneling": false,
          "backchanneling_message_gap": 5,
          "backchanneling_start_delay": 5,
          "ambient_noise": false,
          "ambient_noise_track": "coffee-shop",
          "call_terminate": 90,
          "inbound_limit": -1,
          "whitelist_phone_numbers": null,
          "disallow_unknown_numbers": false,
          "dtmf_enabled": false,
          "auto_reschedule": false,
          "welcome_message_delay": 0,
          "noise_cancellation_level": null,
          "call_hangup_message": null,
          "interruptible_hangup_message": false,
          "check_if_user_online": true,
          "trigger_user_online_message_after": 10,
          "voicemail": false,
          "voicemail_detection_duration": 30,
          "voicemail_check_interval": 7,
          "voicemail_min_transcript_length": 7,
          "voicemail_detection_time": null
        }
      }
    ],
    "agent_welcome_message": "How are you doing Bruce?",
    "webhook_url": "https://your-server.com/webhook",
    "agent_type": "other",
    "ingest_source_config": {
      "source_type": "api",
      "source_url": "https://example.com/api/data",
      "source_auth_token": "abc123",
      "source_name": "leads_sheet_june.csv"
    },
    "calling_guardrails": {
      "call_start_hour": 9,
      "call_end_hour": 17
    },
    "call_summary_enabled": false
  },
  "agent_prompts": {}
}
'

import requests

url = "https://api.bolna.ai/v2/agent"

payload = {
    "agent_config": {
        "agent_name": "Alfred",
        "tasks": [{ "task_config": {
                    "hangup_after_silence": 10,
                    "hangup_after_LLMCall": False,
                    "incremental_delay": 400,
                    "number_of_words_for_interruption": 2,
                    "call_cancellation_prompt": None,
                    "backchanneling": False,
                    "backchanneling_message_gap": 5,
                    "backchanneling_start_delay": 5,
                    "ambient_noise": False,
                    "ambient_noise_track": "coffee-shop",
                    "call_terminate": 90,
                    "inbound_limit": -1,
                    "whitelist_phone_numbers": None,
                    "disallow_unknown_numbers": False,
                    "dtmf_enabled": False,
                    "auto_reschedule": False,
                    "welcome_message_delay": 0,
                    "noise_cancellation_level": None,
                    "call_hangup_message": None,
                    "interruptible_hangup_message": False,
                    "check_if_user_online": True,
                    "trigger_user_online_message_after": 10,
                    "voicemail": False,
                    "voicemail_detection_duration": 30,
                    "voicemail_check_interval": 7,
                    "voicemail_min_transcript_length": 7,
                    "voicemail_detection_time": None
                } }],
        "agent_welcome_message": "How are you doing Bruce?",
        "webhook_url": "https://your-server.com/webhook",
        "agent_type": "other",
        "ingest_source_config": {
            "source_type": "api",
            "source_url": "https://example.com/api/data",
            "source_auth_token": "abc123",
            "source_name": "leads_sheet_june.csv"
        },
        "calling_guardrails": {
            "call_start_hour": 9,
            "call_end_hour": 17
        },
        "call_summary_enabled": False
    },
    "agent_prompts": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_config: {
      agent_name: 'Alfred',
      tasks: [
        {
          task_config: {
            hangup_after_silence: 10,
            hangup_after_LLMCall: false,
            incremental_delay: 400,
            number_of_words_for_interruption: 2,
            call_cancellation_prompt: null,
            backchanneling: false,
            backchanneling_message_gap: 5,
            backchanneling_start_delay: 5,
            ambient_noise: false,
            ambient_noise_track: 'coffee-shop',
            call_terminate: 90,
            inbound_limit: -1,
            whitelist_phone_numbers: null,
            disallow_unknown_numbers: false,
            dtmf_enabled: false,
            auto_reschedule: false,
            welcome_message_delay: 0,
            noise_cancellation_level: null,
            call_hangup_message: null,
            interruptible_hangup_message: false,
            check_if_user_online: true,
            trigger_user_online_message_after: 10,
            voicemail: false,
            voicemail_detection_duration: 30,
            voicemail_check_interval: 7,
            voicemail_min_transcript_length: 7,
            voicemail_detection_time: null
          }
        }
      ],
      agent_welcome_message: 'How are you doing Bruce?',
      webhook_url: 'https://your-server.com/webhook',
      agent_type: 'other',
      ingest_source_config: {
        source_type: 'api',
        source_url: 'https://example.com/api/data',
        source_auth_token: 'abc123',
        source_name: 'leads_sheet_june.csv'
      },
      calling_guardrails: {call_start_hour: 9, call_end_hour: 17},
      call_summary_enabled: false
    },
    agent_prompts: {}
  })
};

fetch('https://api.bolna.ai/v2/agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/v2/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_config' => [
        'agent_name' => 'Alfred',
        'tasks' => [
                [
                                'task_config' => [
                                                                'hangup_after_silence' => 10,
                                                                'hangup_after_LLMCall' => false,
                                                                'incremental_delay' => 400,
                                                                'number_of_words_for_interruption' => 2,
                                                                'call_cancellation_prompt' => null,
                                                                'backchanneling' => false,
                                                                'backchanneling_message_gap' => 5,
                                                                'backchanneling_start_delay' => 5,
                                                                'ambient_noise' => false,
                                                                'ambient_noise_track' => 'coffee-shop',
                                                                'call_terminate' => 90,
                                                                'inbound_limit' => -1,
                                                                'whitelist_phone_numbers' => null,
                                                                'disallow_unknown_numbers' => false,
                                                                'dtmf_enabled' => false,
                                                                'auto_reschedule' => false,
                                                                'welcome_message_delay' => 0,
                                                                'noise_cancellation_level' => null,
                                                                'call_hangup_message' => null,
                                                                'interruptible_hangup_message' => false,
                                                                'check_if_user_online' => true,
                                                                'trigger_user_online_message_after' => 10,
                                                                'voicemail' => false,
                                                                'voicemail_detection_duration' => 30,
                                                                'voicemail_check_interval' => 7,
                                                                'voicemail_min_transcript_length' => 7,
                                                                'voicemail_detection_time' => null
                                ]
                ]
        ],
        'agent_welcome_message' => 'How are you doing Bruce?',
        'webhook_url' => 'https://your-server.com/webhook',
        'agent_type' => 'other',
        'ingest_source_config' => [
                'source_type' => 'api',
                'source_url' => 'https://example.com/api/data',
                'source_auth_token' => 'abc123',
                'source_name' => 'leads_sheet_june.csv'
        ],
        'calling_guardrails' => [
                'call_start_hour' => 9,
                'call_end_hour' => 17
        ],
        'call_summary_enabled' => false
    ],
    'agent_prompts' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/v2/agent"

	payload := strings.NewReader("{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/v2/agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/v2/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "state": "created",
  "version_id": "7e775357-d9d3-4c82-a7d7-b7c3346caf79"
}

{
  "error": 123,
  "message": "<string>"
}

Creates a new voice AI agent. Returns HTTP 201 with { "agent_id": "...", "state": "created", "version_id": "..." }.

The quickest path is creating an agent in the dashboard (Auto Build) and copying its ID. Use the API when you need to programmatically provision agents at scale or integrate agent creation into your deployment pipeline.

Minimal example

The smallest body that produces a working English conversation agent:

Minimal request body

{
  "agent_config": {
    "agent_name": "My First Agent",
    "agent_welcome_message": "Hi! How can I help you today?",
    "tasks": [{
      "task_type": "conversation",
      "toolchain": {
        "execution": "sequential",
        "pipelines": [["transcriber", "llm", "synthesizer"]]
      },
      "tools_config": {
        "llm_agent": {
          "agent_type": "simple_llm_agent",
          "agent_flow_type": "streaming",
          "llm_config": {
            "provider": "openai",
            "model": "gpt-5.4-mini",
            "max_tokens": 150,
            "temperature": 1
          }
        },
        "synthesizer": {
          "provider": "elevenlabs",
          "provider_config": {
            "voice": "Angelica",
            "voice_id": "IkSv4tkouLJ6kYsQA7XD",
            "model": "eleven_turbo_v2_5"
          },
          "stream": true,
          "buffer_size": 250,
          "audio_format": "wav"
        },
        "transcriber": {
          "provider": "deepgram",
          "model": "nova-3",
          "language": "en",
          "stream": true,
          "encoding": "linear16",
          "sampling_rate": 16000,
          "endpointing": 250
        },
        "input": { "provider": "plivo", "format": "wav" },
        "output": { "provider": "plivo", "format": "wav" }
      },
      "task_config": {
        "call_terminate": 90,
        "hangup_after_silence": 10
      }
    }]
  },
  "agent_prompts": {
    "task_1": {
      "system_prompt": "You are a helpful assistant. Keep replies short and friendly."
    }
  }
}

201 Response

{
  "agent_id": "123e4567-e89b-12d3-a456-426655440000",
  "state": "created",
}

Supported providers

tools_config wires four pluggable components. The provider value on the transcriber, synthesizer and input/output blocks is validated at creation time — anything outside the lists below is rejected with 400 Invalid value for provider:'<value>' provided.

LLM

Set on tools_config.llm_agent.llm_config.provider.

`provider`	Models	Notes
`openai`	`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o`	Default. GPT-5-series requires `"temperature": 1`. See OpenAI
`azure-openai`	Your Azure deployment name; an `azure/` prefix is optional and stripped	Needs `AZURE_OPENAI_*` keys in Settings → Integrations. `azure` is an accepted alias. See Azure OpenAI
`anthropic`	`claude-sonnet-5`, `claude-opus-4-8`, `claude-haiku-4-5-20251001`, `claude-fable-5`	See Anthropic
`google`	`gemini-3.7-flash`, `gemini-3.5-flash`, `gemini-3.1-pro`, `gemini-3.1-flash-lite`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`	See Gemini
`deepseek`	`deepseek-v4-flash`, `deepseek-v4-pro`	See DeepSeek
`openrouter`	Any OpenRouter `vendor/model` slug, e.g. `openai/gpt-4o-mini`	One key, many vendors. See OpenRouter
`custom`	Your own model id, with `base_url` and `family` set	Any OpenAI-compatible endpoint. See Custom LLM

Ten more are accepted and routed through LiteLLM using that vendor’s own model ids, without a dedicated reference page: groq, cohere, together, fireworks, deepinfra, perplexity, anyscale, ollama, vllm, ola.

The LLM provider is not checked against a fixed list at creation time, unlike the transcriber and synthesizer. An unroutable provider or model is accepted by POST /v2/agent and only fails once a call runs, so verify it against the table above.

Transcriber

Set on tools_config.transcriber.provider.

`provider`	Models	Best for
`deepgram`	`nova-3`, `nova-3-medical`, `nova-2`, `nova-2-phonecall`, `nova-2-conversationalai` — and Flux: `flux-general-en`, `flux-general-multi`	Lowest latency; reads `keywords` for term biasing. Deepgram, Deepgram Flux
`sarvam`	`saaras:v4`, `saaras:v3` — plus the legacy `saaras:v2.5` and `saarika:v2.5`	Indian languages; reads `context`, and `keywords` on `saaras:v4`. Pass `hi`, not `hi-IN` — see the note below. Sarvam
`openai`	`gpt-realtime-whisper`	Built-in VAD; tune with `delay` and `noise_reduction`. OpenAI
`azure`	`azure`	Enterprise Azure Speech, diarization. Azure
`elevenlabs`	`scribe_v2_realtime`	Also reads `keywords`, capped at 50 terms. ElevenLabs
`assembly`	`universal-3-6-pro`	32 languages with code-switching; reads `keywords` and `context`. AssemblyAI — note the provider value is `assembly`, not `assemblyai`
`gladia`	`solaria-1`	100+ languages, code-switching, sub-300 ms. Gladia
`smallest`	`pulse`	Ultra-low latency. Smallest
`soniox`	`stt-rt-v5`	One model auto-detects and code-switches mid-sentence. Soniox
`gemini`	`gemini-3.5-transcribe-live`	Works on 8 kHz telephony and 16 kHz web audio. Gemini
`google`	`latest_long`	Google Cloud Speech-to-Text

model and language are validated as a pair — an unsupported combination returns 400 Provided language: <language> is not available for the model: <model>.

language takes a plain ISO 639-1 code for every provider, including Sarvam: send "language": "hi". "hi-IN" is rejected, even though Sarvam’s own API uses locale codes — Bolna resolves them for you.

Keyword weights are not carried through. keywords accepts the dashboard’s word:boost form, but the boost is stripped before storage: "Bolna:100,Acme:50,Zeta" is persisted as "Bolna,Acme,Zeta". The terms themselves still apply. Deepgram sends them as keyterm on nova-3 and Flux and as keywords on nova-2 and earlier, and Sarvam reads them on saaras:v4 only. See provider support for every provider that reads this field and its limits.

Synthesizer

Set on tools_config.synthesizer.provider.

`provider`	Models	Best for
`elevenlabs`	`eleven_turbo_v2_5`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4_turbo`	Largest voice library, cloning. ElevenLabs
`cartesia`	`sonic-3.6`, `sonic-3.5`, `sonic-3`	Lowest time-to-first-audio. Cartesia
`sarvam`	`bulbul:v3`	Widest Indian-language coverage; `voice_id` is model-specific. Sarvam
`smallest`	`lightning_v3.1`, `lightning_v3.1_pro`	Ultra-low latency. Smallest
`deepgram`	`aura-2`	English conversational. Deepgram
`polly`	`generative`, `neural`, `standard` (sent as `engine`)	Cost-efficient, broad locales. AWS Polly
`azuretts`	`neural`	Enterprise Azure voices. Azure — note the provider value is `azuretts`
`rime`	`mistv2`, `arcana`	Natural conversational prosody. Rime
`maya`	`Maya 2 Native`	Indic-first; one model covers every language. Maya
`kalpa`	`kalpa-tts-beta-v0.1`, `kalpa-tts-multilingual-beta-v0.1`	Conversational English and Hindi. Kalpa
`soniox`	`tts-rt-v2`	Real-time voices with cloning, `speed` and `reduce_silence`; one key with the Soniox transcriber. Soniox
`openai`	`tts-1`	Works with OpenAI’s own voice names (`alloy`, …), even though List voices returns none for it
`gemini`	—	Accepted as a `provider`, but no Gemini TTS model currently resolves

Resolve a valid model + voice_id pair with List TTS providers and List voices before creating the agent — the voice catalog changes over time, and availability varies by language and by whether you have connected your own provider key.

language inside provider_config is required for most providers — cartesia, sarvam, smallest, rime, azuretts, gemini, soniox and polly. Leaving it out fails with 400 Tools Config > Voice > Language: This field is required, even though the agent already has a transcriber language. elevenlabs, deepgram and openai do not take it at all, and it is optional on maya (defaults to en) and kalpa.

Telephony

Set on tools_config.input.provider and tools_config.output.provider. twilio, plivo, exotel, vobiz and sip-trunk are the telephony providers. Use wav as the format for twilio, plivo, exotel and vobiz, and ulaw for sip-trunk — Twilio and sip-trunk stream mulaw audio, the rest linear16. See Supported telephony providers. The enum also accepts freeswitch, used for web calling (linear16, 16 kHz in / 24 kHz out), and default and database, which are internal.

To mix providers per language in one agent — for example Deepgram + Cartesia for English and ElevenLabs + Sarvam for Hindi — use multilingual_config. See the Multilingual Config Reference.

To replace the transcriber, LLM and synthesizer with a single realtime model, set tools_config.s2s and leave the other three null. See Speech-to-Speech.

Common 400 errors

Message	Fix
`agent_config is required`	Wrap your config in `{ "agent_config": { ... } }`
`tasks is required`	The `tasks` array must have at least one entry
`toolchain.pipelines must be array of arrays`	Use `[["transcriber","llm","synthesizer"]]`, not `["transcriber","llm","synthesizer"]`
`For GPT-5 models, temperature must be 1`	Send `"temperature": 1` in `llm_config`. GPT-5-series models accept no other value, and the field defaults to `0.1` when omitted
`reasoning_effort '<value>' is not supported for model '<model>'`	Use an effort the model accepts — see the per-model table
`Invalid value for provider:'<value>' provided. Supported values: [...]`	The transcriber, synthesizer or input/output `provider` is not one of the supported values — see Supported providers
`Model '<model>' is not available for provider '<provider>'`	The synthesizer `provider_config.model` does not exist for that provider. Check List TTS providers
`Provided voice: <voice> is not available for the provider: <provider>`	The `voice` / `voice_id` pair is not in that provider’s catalog. Check List voices
`Provided language: <language> is not available for the model: <model>`	The transcriber `model` and `language` do not go together — see the transcriber table

Next steps

After creating an agent, place a call with POST /call using the returned agent_id. See the API Quickstart for a complete end-to-end example.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Creates a new agent

agent_config

object

required

Configuration of the agent

Show child attributes

agent_prompts

object

required

Prompts to be provided to the agent. It can have multiple tasks of the form task_<task_id>

Show child attributes

Response

agent created response

agent_id

string<uuid>

state

enum<string>

Available options:

created

Example:

"created"

version_id

string<uuid>

Id of the initial version created alongside the agent. Use it with the agent version APIs to pin or roll back a configuration.

Example:

"7e775357-d9d3-4c82-a7d7-b7c3346caf79"

cURL

curl --request POST \
  --url https://api.bolna.ai/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_config": {
    "agent_name": "Alfred",
    "tasks": [
      {
        "task_config": {
          "hangup_after_silence": 10,
          "hangup_after_LLMCall": false,
          "incremental_delay": 400,
          "number_of_words_for_interruption": 2,
          "call_cancellation_prompt": null,
          "backchanneling": false,
          "backchanneling_message_gap": 5,
          "backchanneling_start_delay": 5,
          "ambient_noise": false,
          "ambient_noise_track": "coffee-shop",
          "call_terminate": 90,
          "inbound_limit": -1,
          "whitelist_phone_numbers": null,
          "disallow_unknown_numbers": false,
          "dtmf_enabled": false,
          "auto_reschedule": false,
          "welcome_message_delay": 0,
          "noise_cancellation_level": null,
          "call_hangup_message": null,
          "interruptible_hangup_message": false,
          "check_if_user_online": true,
          "trigger_user_online_message_after": 10,
          "voicemail": false,
          "voicemail_detection_duration": 30,
          "voicemail_check_interval": 7,
          "voicemail_min_transcript_length": 7,
          "voicemail_detection_time": null
        }
      }
    ],
    "agent_welcome_message": "How are you doing Bruce?",
    "webhook_url": "https://your-server.com/webhook",
    "agent_type": "other",
    "ingest_source_config": {
      "source_type": "api",
      "source_url": "https://example.com/api/data",
      "source_auth_token": "abc123",
      "source_name": "leads_sheet_june.csv"
    },
    "calling_guardrails": {
      "call_start_hour": 9,
      "call_end_hour": 17
    },
    "call_summary_enabled": false
  },
  "agent_prompts": {}
}
'

import requests

url = "https://api.bolna.ai/v2/agent"

payload = {
    "agent_config": {
        "agent_name": "Alfred",
        "tasks": [{ "task_config": {
                    "hangup_after_silence": 10,
                    "hangup_after_LLMCall": False,
                    "incremental_delay": 400,
                    "number_of_words_for_interruption": 2,
                    "call_cancellation_prompt": None,
                    "backchanneling": False,
                    "backchanneling_message_gap": 5,
                    "backchanneling_start_delay": 5,
                    "ambient_noise": False,
                    "ambient_noise_track": "coffee-shop",
                    "call_terminate": 90,
                    "inbound_limit": -1,
                    "whitelist_phone_numbers": None,
                    "disallow_unknown_numbers": False,
                    "dtmf_enabled": False,
                    "auto_reschedule": False,
                    "welcome_message_delay": 0,
                    "noise_cancellation_level": None,
                    "call_hangup_message": None,
                    "interruptible_hangup_message": False,
                    "check_if_user_online": True,
                    "trigger_user_online_message_after": 10,
                    "voicemail": False,
                    "voicemail_detection_duration": 30,
                    "voicemail_check_interval": 7,
                    "voicemail_min_transcript_length": 7,
                    "voicemail_detection_time": None
                } }],
        "agent_welcome_message": "How are you doing Bruce?",
        "webhook_url": "https://your-server.com/webhook",
        "agent_type": "other",
        "ingest_source_config": {
            "source_type": "api",
            "source_url": "https://example.com/api/data",
            "source_auth_token": "abc123",
            "source_name": "leads_sheet_june.csv"
        },
        "calling_guardrails": {
            "call_start_hour": 9,
            "call_end_hour": 17
        },
        "call_summary_enabled": False
    },
    "agent_prompts": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_config: {
      agent_name: 'Alfred',
      tasks: [
        {
          task_config: {
            hangup_after_silence: 10,
            hangup_after_LLMCall: false,
            incremental_delay: 400,
            number_of_words_for_interruption: 2,
            call_cancellation_prompt: null,
            backchanneling: false,
            backchanneling_message_gap: 5,
            backchanneling_start_delay: 5,
            ambient_noise: false,
            ambient_noise_track: 'coffee-shop',
            call_terminate: 90,
            inbound_limit: -1,
            whitelist_phone_numbers: null,
            disallow_unknown_numbers: false,
            dtmf_enabled: false,
            auto_reschedule: false,
            welcome_message_delay: 0,
            noise_cancellation_level: null,
            call_hangup_message: null,
            interruptible_hangup_message: false,
            check_if_user_online: true,
            trigger_user_online_message_after: 10,
            voicemail: false,
            voicemail_detection_duration: 30,
            voicemail_check_interval: 7,
            voicemail_min_transcript_length: 7,
            voicemail_detection_time: null
          }
        }
      ],
      agent_welcome_message: 'How are you doing Bruce?',
      webhook_url: 'https://your-server.com/webhook',
      agent_type: 'other',
      ingest_source_config: {
        source_type: 'api',
        source_url: 'https://example.com/api/data',
        source_auth_token: 'abc123',
        source_name: 'leads_sheet_june.csv'
      },
      calling_guardrails: {call_start_hour: 9, call_end_hour: 17},
      call_summary_enabled: false
    },
    agent_prompts: {}
  })
};

fetch('https://api.bolna.ai/v2/agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/v2/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_config' => [
        'agent_name' => 'Alfred',
        'tasks' => [
                [
                                'task_config' => [
                                                                'hangup_after_silence' => 10,
                                                                'hangup_after_LLMCall' => false,
                                                                'incremental_delay' => 400,
                                                                'number_of_words_for_interruption' => 2,
                                                                'call_cancellation_prompt' => null,
                                                                'backchanneling' => false,
                                                                'backchanneling_message_gap' => 5,
                                                                'backchanneling_start_delay' => 5,
                                                                'ambient_noise' => false,
                                                                'ambient_noise_track' => 'coffee-shop',
                                                                'call_terminate' => 90,
                                                                'inbound_limit' => -1,
                                                                'whitelist_phone_numbers' => null,
                                                                'disallow_unknown_numbers' => false,
                                                                'dtmf_enabled' => false,
                                                                'auto_reschedule' => false,
                                                                'welcome_message_delay' => 0,
                                                                'noise_cancellation_level' => null,
                                                                'call_hangup_message' => null,
                                                                'interruptible_hangup_message' => false,
                                                                'check_if_user_online' => true,
                                                                'trigger_user_online_message_after' => 10,
                                                                'voicemail' => false,
                                                                'voicemail_detection_duration' => 30,
                                                                'voicemail_check_interval' => 7,
                                                                'voicemail_min_transcript_length' => 7,
                                                                'voicemail_detection_time' => null
                                ]
                ]
        ],
        'agent_welcome_message' => 'How are you doing Bruce?',
        'webhook_url' => 'https://your-server.com/webhook',
        'agent_type' => 'other',
        'ingest_source_config' => [
                'source_type' => 'api',
                'source_url' => 'https://example.com/api/data',
                'source_auth_token' => 'abc123',
                'source_name' => 'leads_sheet_june.csv'
        ],
        'calling_guardrails' => [
                'call_start_hour' => 9,
                'call_end_hour' => 17
        ],
        'call_summary_enabled' => false
    ],
    'agent_prompts' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/v2/agent"

	payload := strings.NewReader("{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/v2/agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/v2/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_config\": {\n    \"agent_name\": \"Alfred\",\n    \"tasks\": [\n      {\n        \"task_config\": {\n          \"hangup_after_silence\": 10,\n          \"hangup_after_LLMCall\": false,\n          \"incremental_delay\": 400,\n          \"number_of_words_for_interruption\": 2,\n          \"call_cancellation_prompt\": null,\n          \"backchanneling\": false,\n          \"backchanneling_message_gap\": 5,\n          \"backchanneling_start_delay\": 5,\n          \"ambient_noise\": false,\n          \"ambient_noise_track\": \"coffee-shop\",\n          \"call_terminate\": 90,\n          \"inbound_limit\": -1,\n          \"whitelist_phone_numbers\": null,\n          \"disallow_unknown_numbers\": false,\n          \"dtmf_enabled\": false,\n          \"auto_reschedule\": false,\n          \"welcome_message_delay\": 0,\n          \"noise_cancellation_level\": null,\n          \"call_hangup_message\": null,\n          \"interruptible_hangup_message\": false,\n          \"check_if_user_online\": true,\n          \"trigger_user_online_message_after\": 10,\n          \"voicemail\": false,\n          \"voicemail_detection_duration\": 30,\n          \"voicemail_check_interval\": 7,\n          \"voicemail_min_transcript_length\": 7,\n          \"voicemail_detection_time\": null\n        }\n      }\n    ],\n    \"agent_welcome_message\": \"How are you doing Bruce?\",\n    \"webhook_url\": \"https://your-server.com/webhook\",\n    \"agent_type\": \"other\",\n    \"ingest_source_config\": {\n      \"source_type\": \"api\",\n      \"source_url\": \"https://example.com/api/data\",\n      \"source_auth_token\": \"abc123\",\n      \"source_name\": \"leads_sheet_june.csv\"\n    },\n    \"calling_guardrails\": {\n      \"call_start_hour\": 9,\n      \"call_end_hour\": 17\n    },\n    \"call_summary_enabled\": false\n  },\n  \"agent_prompts\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "state": "created",
  "version_id": "7e775357-d9d3-4c82-a7d7-b7c3346caf79"
}

{
  "error": 123,
  "message": "<string>"
}

Get started

Voice agents

Telephony

Workflows

Account

Legacy

Create voice AI agent API

Minimal example

Supported providers

LLM

Transcriber

Synthesizer

Telephony

Common 400 errors

Next steps

Authorizations

Body

Response

​Minimal example

​Supported providers

​LLM

​Transcriber

​Synthesizer

​Telephony

​Common 400 errors

​Next steps

Authorizations

Body

Response

Minimal example

Supported providers

LLM

Transcriber

Synthesizer

Telephony

Common 400 errors

Next steps