Skip to main content
POST
/
v1
/
convai
/
agents
/
create
Create Agent
curl --request POST \
  --url https://api.threetone.in/v1/convai/agents/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "conversation_config": {
    "asr": {
      "quality": "high",
      "provider": "elevenlabs",
      "user_input_audio_format": "pcm_16000",
      "keywords": [
        "<string>"
      ]
    },
    "turn": {
      "turn_timeout": 7,
      "initial_wait_time": 123,
      "silence_end_call_timeout": -1,
      "soft_timeout_config": {
        "timeout_seconds": -1,
        "message": "Hhmmmm...yeah.",
        "use_llm_generated_message": false
      },
      "speculative_turn": false
    },
    "tts": {
      "model_id": "eleven_flash_v2",
      "voice_id": "cjVigY5qzO86Huf0OWal",
      "supported_voices": [
        {
          "label": "<string>",
          "voice_id": "<string>",
          "description": "<string>",
          "language": "<string>",
          "model_family": "<string>",
          "optimize_streaming_latency": 0,
          "stability": 0.5,
          "speed": 0.95,
          "similarity_boost": 0.5
        }
      ],
      "expressive_mode": true,
      "suggested_audio_tags": [
        {
          "tag": "<string>",
          "description": "<string>"
        }
      ],
      "agent_output_audio_format": "pcm_16000",
      "optimize_streaming_latency": 3,
      "stability": 0.5,
      "speed": 1,
      "similarity_boost": 0.8,
      "text_normalisation_type": "system_prompt",
      "pronunciation_dictionary_locators": [
        {
          "pronunciation_dictionary_id": "<string>",
          "version_id": "<string>"
        }
      ]
    },
    "conversation": {
      "text_only": false,
      "max_duration_seconds": 600,
      "client_events": [
        "conversation_initiation_metadata"
      ],
      "file_input": {
        "enabled": true,
        "max_files_per_conversation": 10
      },
      "monitoring_enabled": false,
      "monitoring_events": [
        "conversation_initiation_metadata"
      ]
    },
    "language_presets": {},
    "agent": {
      "first_message": "",
      "language": "en",
      "dynamic_variables": {
        "dynamic_variable_placeholders": {
          "user_name": "John Doe"
        }
      },
      "disable_first_message_interruptions": false,
      "max_conversation_duration_message": "",
      "prompt": {
        "knowledge_base": [],
        "llm": "gemini-2.5-flash",
        "max_tokens": -1,
        "mcp_server_ids": [],
        "native_mcp_server_ids": [],
        "prompt": "You are a helpful assistant that can answer questions about the topic of the conversation.",
        "temperature": 0,
        "tool_ids": []
      }
    }
  },
  "name": "My agent"
}
'
{
  "agent_id": "<string>"
}

Authorizations

x-api-key
string
header
required

API key for programmatic access

Headers

xi-api-key
string | null

Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

Query Parameters

enable_versioning
boolean
default:false

Enable versioning for the agent

Body

application/json

Request body for POST /v1/convai/agents/create.

conversation_config
ConversationalConfigAPIModel-Input · 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
AgentWorkflowRequestModel · 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",
"Eleven"
]

Response

Successful Response

agent_id
string
required

ID of the created agent