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. 
{
  "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"
      ]
    }
  },
  "webhook_url": "https://yourapi.com/webhooks/call-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.

Response

201
application/json

Successful Response

Schema for assistant response.