POST
/
api
/
v1
/
assistants
{
  "name": "<string>",
  "description": "<string>",
  "llm_provider": "<string>",
  "llm_provider_config": {
    "api_key": "<string>",
    "base_url": "<string>",
    "model": "gpt-4o-mini",
    "custom_config": {}
  },
  "twilio_config": {
    "account_sid": "<string>",
    "auth_token": "<string>"
  },
  "llm_settings": {
    "temperature": 0.5,
    "max_tokens": 1000,
    "system_prompt": "You are a helpful assistant that can answer questions and help with tasks.",
    "welcome_message": "<string>",
    "top_p": 1,
    "frequency_penalty": 0,
    "presence_penalty": 0,
    "stop_sequences": [
      "<string>"
    ]
  },
  "webhook_url": "<string>",
  "interruption_settings": {
    "interruption_threshold": 3,
    "min_speaking_time": 0.5,
    "interruption_cooldown": 2
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "rachel",
    "model_id": "<string>",
    "latency": 1,
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0,
    "use_speaker_boost": true,
    "provider_config": {}
  },
  "stt_settings": {
    "model": "nova-2",
    "language": "en-US",
    "punctuate": true,
    "interim_results": true,
    "endpointing": {
      "silence_threshold": 500,
      "min_silence_duration": 500
    },
    "utterance_end_ms": 1000,
    "vad_turnoff": 500,
    "smart_format": true,
    "keywords": [
      {
        "keyword": "<string>",
        "intensifier": 1
      }
    ],
    "keyterms": [
      "<string>"
    ],
    "audio_denoising": false
  },
  "end_call_message": "<string>",
  "transfer_call_message": "<string>",
  "idle_message": "<string>",
  "max_idle_messages": 123,
  "idle_timeout": 123,
  "tools_settings": {
    "enabled_tools": [
      "<string>"
    ],
    "end_call": {
      "enabled": false,
      "scenarios": [
        "<string>"
      ],
      "custom_message": "<string>"
    },
    "transfer_call": {
      "enabled": false,
      "scenarios": [
        "<string>"
      ],
      "transfer_numbers": [
        "<string>"
      ],
      "custom_message": "<string>"
    },
    "custom_tools": [
      {}
    ]
  },
  "rag_settings": {
    "enabled": false,
    "search_limit": 3,
    "similarity_threshold": 0.7,
    "embedding_model": "text-embedding-3-small",
    "chunking_strategy": "recursive",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "auto_process": true,
    "include_metadata": true,
    "context_window_tokens": 4000
  },
  "llm_fallback_providers": {
    "enabled": false,
    "fallbacks": [
      {
        "provider": "<string>",
        "api_key": "<string>",
        "base_url": "<string>",
        "model": "<string>"
      }
    ]
  },
  "custom_settings": {},
  "is_active": true,
  "id": 123,
  "organization_id": 123,
  "user_id": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
This endpoint allows you to create a new, fully configured voice AI assistant. The parameters available via the API directly correspond to the settings you can configure in the assistant creation form in the web UI. A successful request will create the assistant within your organization and return the full assistant object, including its unique ID.

​
Request Body

The request body is a JSON object containing the assistant’s configuration. The parameters are organized into logical groups that mirror the sections in the UI. Many parameters are conditional based on the provider or options you select.

​
Example Request

Here is an example payload that mirrors the fields available in the UI to create a sophisticated customer service assistant. Note that fields like scenarios and transfer_numbers expect a JSON array of strings.

​
Example: Twilio Assistant

{
  "name": "ServiceBot 5000",
  "description": "Handles initial customer service questions and escalations.",
  "is_active": true,
  "llm_provider": "openai",
  "llm_provider_config": {
    "model": "gpt-4o-mini",
    "api_key": "sk-your-openai-api-key"
  },
  "llm_settings": {
    "temperature": 0.7,
    "max_tokens": 1000,
    "system_prompt": "You are a friendly and efficient customer support agent. Your goal is to help with common questions and transfer to a human when requested.",
    "welcome_message": "Hello! Thanks for calling support. How can I assist you today?"
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "rachel",
    "model_id": "eleven_flash_v2_5",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.0,
    "use_speaker_boost": true
  },
  "stt_settings": {
    "model": "nova-2",
    "language": "en-US",
    "keywords": [
        {"keyword": "agent", "intensifier": 1.5},
        {"keyword": "human"},
        {"keyword": "representative"}
    ]
  },
  "interruption_settings": {
    "interruption_threshold": 3,
    "min_speaking_time": 0.5,
    "interruption_cooldown": 2.0
  },
  "idle_message": "Are you still there? I'm here to help if you need anything.",
  "max_idle_messages": 2,
  "idle_timeout": 20,
  "tools_settings": {
    "transfer_call": {
      "enabled": true,
      "scenarios": [
        "speak to an agent",
        "talk to a human",
        "transfer me to a representative"
      ],
      "transfer_numbers": [
        "+18005551212"
      ]
    }
  },
  "twilio_config": {
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token"
  },
  "webhook_url": "https://yourapi.com/webhooks/call-events"
}

​
Example: Telnyx Assistant

{
  "name": "SalesBot Pro",
  "description": "Modern sales assistant using Telnyx for competitive call rates.",
  "is_active": true,
  "llm_provider": "openai",
  "llm_provider_config": {
    "model": "gpt-4o-mini",
    "api_key": "sk-your-openai-api-key"
  },
  "llm_settings": {
    "temperature": 0.8,
    "max_tokens": 1000,
    "system_prompt": "You are an enthusiastic sales representative. Help qualify leads and schedule demos.",
    "welcome_message": "Hi there! Thanks for your interest in our product. How can I help you today?"
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "charlie",
    "model_id": "eleven_flash_v2_5",
    "stability": 0.6,
    "similarity_boost": 0.8,
    "use_speaker_boost": true
  },
  "stt_settings": {
    "model": "nova-3",
    "language": "en-US",
    "keyterms": ["demo", "pricing", "features", "schedule"]
  },
  "telnyx_config": {
    "api_key": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "connection_id": "1234567890"
  },
  "webhook_url": "https://yourapi.com/webhooks/telnyx-events"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Schema for creating a new assistant.

​
name
string
required
​
description
string | null
​
llm_provider
string | null
default:openai

LLM provider: openai, anthropic, gemini, xai, groq, custom

​
llm_provider_config
object

Configuration for the selected LLM provider.

​
openai_api_key
string | null
​
custom_llm_url
string | null
​
deepgram_api_key
string | null
​
elevenlabs_api_key
string | null
​
twilio_config
object

Twilio account configuration.

​
twilio_account_sid
string | null
​
twilio_auth_token
string | null
​
llm_settings
object

Settings for the Large Language Model.

​
webhook_url
string | null
​
interruption_settings
object

Settings for call interruption behavior.

​
tts_settings
object

Settings for Text-to-Speech (TTS) service.

​
stt_settings
object

Settings for Speech-to-Text (STT) service.

​
end_call_message
string | null
​
transfer_call_message
string | null
​
idle_message
string | null
default:Are you still there? I'm here to help if you need anything.
​
max_idle_messages
integer | null
​
idle_timeout
integer | null
​
tools_settings
object

Settings for integrated tools.

​
rag_settings
object

Settings for Retrieval-Augmented Generation (RAG).

​
llm_fallback_providers
object

Settings for LLM fallback providers.

​
custom_settings
object | null
​
is_active
boolean | null
default:true

Response

Successful Response

Schema for assistant response.

​
name
string
required
​
id
integer
required
​
organization_id
integer
required
​
user_id
integer
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
description
string | null
​
llm_provider
string | null
default:openai

LLM provider: openai, anthropic, gemini, xai, groq, custom

​
llm_provider_config
object

Configuration for the selected LLM provider.

​
twilio_config
object

Twilio account configuration.

​
llm_settings
object

Settings for the Large Language Model.

​
webhook_url
string | null
​
interruption_settings
object

Settings for call interruption behavior.

​
tts_settings
object

Settings for Text-to-Speech (TTS) service.

​
stt_settings
object

Settings for Speech-to-Text (STT) service.

​
end_call_message
string | null
​
transfer_call_message
string | null
​
idle_message
string | null
default:Are you still there? I'm here to help if you need anything.
​
max_idle_messages
integer | null
​
idle_timeout
integer | null
​
tools_settings
object

Settings for integrated tools.

​
rag_settings
object

Settings for Retrieval-Augmented Generation (RAG).

​
llm_fallback_providers
object

Settings for LLM fallback providers.

​
custom_settings
object | null
​
is_active
boolean | null
default:true