Skip to main content
POST
/
v1
/
voiceai
/
agents
/
create
Create Agent
curl --request POST \
  --url https://api.example.com/v1/voiceai/agents/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "conversation_config": {
    "turn": {
      "turn_timeout": 7,
      "initial_wait_time": 123,
      "silence_end_call_timeout": -1,
      "soft_timeout_config": {
        "message": "Hhmmmm...yeah give me a second...",
        "timeout_seconds": -1
      },
      "mode": "turn",
      "turn_eagerness": "normal"
    },
    "tts": {
      "voice_id": "<string>",
      "supported_voices": [
        {
          "voice_id": "<string>",
          "language": "<string>"
        }
      ]
    },
    "conversation": {
      "text_only": false,
      "max_duration_seconds": 600,
      "client_events": [
        "conversation_initiation_metadata"
      ],
      "monitoring_enabled": false,
      "monitoring_events": [
        "conversation_initiation_metadata"
      ]
    },
    "language_presets": {},
    "agent": {
      "first_message": "",
      "language": "en",
      "dynamic_variables": {
        "dynamic_variable_placeholders": {}
      },
      "disable_first_message_interruptions": false,
      "prompt": {
        "prompt": "",
        "llm": "gemini-2.5-flash",
        "reasoning_effort": "none",
        "thinking_budget": 123,
        "temperature": 0,
        "max_tokens": -1,
        "tool_ids": [
          "<string>"
        ],
        "built_in_tools": {
          "end_call": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "language_detection": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "transfer_to_agent": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "transfer_to_number": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "skip_turn": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "play_keypad_touch_tone": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          },
          "voicemail_detection": {
            "name": "<string>",
            "params": {
              "system_tool_type": "end_call"
            },
            "type": "system",
            "description": "",
            "response_timeout_secs": 20,
            "disable_interruptions": false,
            "force_pre_tool_speech": false,
            "assignments": [
              {
                "dynamic_variable": "<string>",
                "value_path": "<string>",
                "source": "response"
              }
            ],
            "tool_call_sound": "typing",
            "tool_call_sound_behavior": "auto"
          }
        },
        "knowledge_base": [
          {
            "id": "123",
            "name": "My Knowledge Base",
            "type": "file",
            "usage_mode": "auto"
          }
        ],
        "ignore_default_personality": false,
        "rag": {
          "enabled": false,
          "embedding_model": "gemini-embedding-001",
          "max_vector_distance": 0.6,
          "max_documents_length": 50000,
          "max_retrieved_rag_chunks_count": 20,
          "query_rewrite_prompt_override": "<string>"
        },
        "timezone": "<string>"
      }
    }
  },
  "name": "My agent"
}
'
{
  "agent_id": "<string>"
}

Authorizations

​
x-api-key
string
header
required

API key for programmatic access

Body

application/json
​
conversation_config
ConversationalConfigAPIModelInput · object
required

Conversation configuration for an agent

​
platform_settings
AgentPlatformSettingsRequestModel · object

Platform settings for the agent are all settings that aren't related to the conversation orchestration and content.

​
workflow
Workflow · object

Workflow for the agent. This is used to define the flow of the conversation and how the agent interacts with tools.

​
name
string | null

A name to make the agent easier to find

Example:

"My agent"

​
tags
string[] | null

Tags to help classify and filter the agent

Example:
["Customer Support", "Technical Help"]

Response

Successful Response

​
agent_id
string
required

ID of the created agent