Create Retell LLM

POST

create-retell-llm

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const llmResponse = await client.llm.create();

console.log(llmResponse.llm_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
llm_response = client.llm.create()
print(llm_response.llm_id)

curl --request POST \
  --url https://api.retellai.com/create-retell-llm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_config": {
    "type": "cascading",
    "backup": {
      "kick_in_timeout_ms": 30150
    },
    "temperature": 0
  },
  "backup_model": {
    "type": "cascading",
    "high_priority": true,
    "ultrafast": true,
    "backup_kick_in_timeout": 30150
  },
  "model": "gpt-5.6-terra",
  "s2s_model": "gpt-realtime-1.5",
  "model_temperature": 0,
  "model_high_priority": true,
  "model_ultrafast": true,
  "knowledge_base_ids": [
    "<string>"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "begin_after_user_silence_ms": 2000,
  "begin_message": "Hey I am a virtual assistant calling from Retell Hospital.",
  "general_prompt": "You are ...",
  "voice_prompt": "You are a friendly voice assistant for ...",
  "general_tools": [
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call with user."
    }
  ],
  "states": [
    {
      "name": "information_collection",
      "state_prompt": "You will follow the steps below to collect information...",
      "edges": [
        {
          "destination_state_name": "appointment_booking",
          "description": "Transition to book an appointment."
        }
      ],
      "tools": [
        {
          "type": "transfer_call",
          "name": "transfer_to_support",
          "description": "Transfer to the support team.",
          "transfer_destination": {
            "type": "predefined",
            "number": "16175551212",
            "ignore_e164_validation": false
          },
          "transfer_option": {
            "type": "cold_transfer",
            "show_transferee_as_caller": false
          }
        }
      ]
    },
    {
      "name": "appointment_booking",
      "state_prompt": "You will follow the steps below to book an appointment...",
      "tools": [
        {
          "type": "custom",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "url": "https://api.example.com/book-appointment",
          "method": "POST"
        }
      ]
    }
  ],
  "starting_state": "information_collection",
  "default_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "is_transfer_llm": false
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/create-retell-llm",
  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([
    'model_config' => [
        'type' => 'cascading',
        'backup' => [
                'kick_in_timeout_ms' => 30150
        ],
        'temperature' => 0
    ],
    'backup_model' => [
        'type' => 'cascading',
        'high_priority' => true,
        'ultrafast' => true,
        'backup_kick_in_timeout' => 30150
    ],
    'model' => 'gpt-5.6-terra',
    's2s_model' => 'gpt-realtime-1.5',
    'model_temperature' => 0,
    'model_high_priority' => true,
    'model_ultrafast' => true,
    'knowledge_base_ids' => [
        '<string>'
    ],
    'kb_config' => [
        'top_k' => 3,
        'filter_score' => 0.6
    ],
    'begin_after_user_silence_ms' => 2000,
    'begin_message' => 'Hey I am a virtual assistant calling from Retell Hospital.',
    'general_prompt' => 'You are ...',
    'voice_prompt' => 'You are a friendly voice assistant for ...',
    'general_tools' => [
        [
                'type' => 'end_call',
                'name' => 'end_call',
                'description' => 'End the call with user.'
        ]
    ],
    'states' => [
        [
                'name' => 'information_collection',
                'state_prompt' => 'You will follow the steps below to collect information...',
                'edges' => [
                                [
                                                                'destination_state_name' => 'appointment_booking',
                                                                'description' => 'Transition to book an appointment.'
                                ]
                ],
                'tools' => [
                                [
                                                                'type' => 'transfer_call',
                                                                'name' => 'transfer_to_support',
                                                                'description' => 'Transfer to the support team.',
                                                                'transfer_destination' => [
                                                                                                                                'type' => 'predefined',
                                                                                                                                'number' => '16175551212',
                                                                                                                                'ignore_e164_validation' => false
                                                                ],
                                                                'transfer_option' => [
                                                                                                                                'type' => 'cold_transfer',
                                                                                                                                'show_transferee_as_caller' => false
                                                                ]
                                ]
                ]
        ],
        [
                'name' => 'appointment_booking',
                'state_prompt' => 'You will follow the steps below to book an appointment...',
                'tools' => [
                                [
                                                                'type' => 'custom',
                                                                'name' => 'book_appointment',
                                                                'description' => 'Book an annual check up.',
                                                                'url' => 'https://api.example.com/book-appointment',
                                                                'method' => 'POST'
                                ]
                ]
        ]
    ],
    'starting_state' => 'information_collection',
    'default_dynamic_variables' => [
        'customer_name' => 'John Doe'
    ],
    'mcps' => [
        [
                'name' => '<string>',
                'url' => '<string>',
                'headers' => [
                                'Authorization' => 'Bearer 1234567890'
                ],
                'query_params' => [
                                'index' => '1',
                                'key' => 'value'
                ],
                'timeout_ms' => 123
        ]
    ],
    'is_transfer_llm' => false
  ]),
  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.retellai.com/create-retell-llm"

	payload := strings.NewReader("{\n  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\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.retellai.com/create-retell-llm")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/create-retell-llm")

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  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\n}"

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

{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "last_modification_timestamp": 1703413636133,
  "version": 0,
  "is_published": false,
  "model_config": {
    "type": "cascading",
    "primary": {
      "model": "gpt-4.1",
      "tier": "standard"
    },
    "backup": {
      "model": "gpt-4.1",
      "tier": "standard",
      "kick_in_timeout_ms": 30150
    },
    "temperature": 0
  },
  "backup_model": {
    "type": "cascading",
    "model": "gpt-4.1",
    "high_priority": true,
    "ultrafast": true,
    "backup_kick_in_timeout": 30150
  },
  "model": "gpt-5.6-terra",
  "s2s_model": "gpt-realtime-1.5",
  "model_temperature": 0,
  "model_high_priority": true,
  "model_ultrafast": true,
  "knowledge_base_ids": [
    "<string>"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "start_speaker": "user",
  "begin_after_user_silence_ms": 2000,
  "begin_message": "Hey I am a virtual assistant calling from Retell Hospital.",
  "general_prompt": "You are ...",
  "voice_prompt": "You are a friendly voice assistant for ...",
  "general_tools": [
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call with user."
    }
  ],
  "states": [
    {
      "name": "information_collection",
      "state_prompt": "You will follow the steps below to collect information...",
      "edges": [
        {
          "destination_state_name": "appointment_booking",
          "description": "Transition to book an appointment."
        }
      ],
      "tools": [
        {
          "type": "transfer_call",
          "name": "transfer_to_support",
          "description": "Transfer to the support team.",
          "transfer_destination": {
            "type": "predefined",
            "number": "16175551212",
            "ignore_e164_validation": false
          },
          "transfer_option": {
            "type": "cold_transfer",
            "show_transferee_as_caller": false
          }
        }
      ]
    },
    {
      "name": "appointment_booking",
      "state_prompt": "You will follow the steps below to book an appointment...",
      "tools": [
        {
          "type": "custom",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "url": "https://api.example.com/book-appointment",
          "method": "POST"
        }
      ]
    }
  ],
  "starting_state": "information_collection",
  "default_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "is_transfer_llm": false
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json

Override properties for Retell LLM configuration in agent override requests.

model_config

object

Model settings for the response engine. type decides which models primary and backup accept. On update, each top-level key replaces the current one and omitted keys are kept; set backup to null to remove it. Changing type requires primary and clears backup, while temperature carries over. In agent_override, type is required whenever primary is set; setting backup to null disables it for that call only.

Option 1
Option 2
Option 3

Show child attributes

backup_model

object

deprecated

Backup models are supported only for call agents. Response engines with a backup model cannot be used by chat agents.

Option 1
Option 2
Option 3
Option 4

Show child attributes

model

enum<string> | null

deprecated

Deprecated, use model_config.primary. Ignored when model_config is set.

Available options:

gpt-4.1,

gpt-4.1-mini,

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-5.1,

gpt-5.2,

gpt-5.4,

gpt-5.4-mini,

gpt-5.4-nano,

gpt-5.5,

gpt-5.6-terra,

gpt-5.6-luna,

gpt-6-astra,

gpt-6-sol,

gpt-6.1-sol,

gpt-6.1-terra,

gpt-6-luna,

tell-1,

claude-4.6-sonnet,

claude-5-opus,

claude-5.5-opus,

claude-5-sonnet,

claude-5.5-sonnet,

claude-5.5-haiku,

claude-4.5-haiku,

gemini-3.0-flash,

gemini-3.1-flash-lite,

gemini-3.5-flash,

gemini-3.5-flash-lite,

gemini-3.6-flash,

gemini-3.7-flash,

gemini-3.8-flash,

gemini-4-hydrogen,

gemini-4-carbon,

gemini-4-argon,

null

Example:

"gpt-5.6-terra"

s2s_model

enum<string> | null

deprecated

Deprecated, use model_config with type s2s. Ignored when model_config is set.

Available options:

gpt-realtime-2.1,

gpt-realtime-2.1-mini,

gpt-realtime-2,

gpt-realtime-1.5,

gpt-realtime,

gpt-realtime-mini,

grok-voice-3.0,

null

Example:

"gpt-realtime-1.5"

model_temperature

number

deprecated

Deprecated, use model_config.temperature. Ignored when model_config is set.

Example:

0

model_high_priority

boolean | null

deprecated

Deprecated, use model_config.primary.tier fast. Ignored when model_config is set.

Example:

true

model_ultrafast

boolean | null

deprecated

Deprecated, use model_config.primary.tier ultrafast. Ignored when model_config is set.

Example:

true

knowledge_base_ids

string[] | null

A list of knowledge base ids to use for this resource.

kb_config

object | null

Knowledge base configuration for RAG retrieval.

Show child attributes

start_speaker

enum<string>

The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.

Available options:

user,

agent

begin_after_user_silence_ms

integer | null

If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.

Example:

2000

begin_message

string | null

First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.

Example:

"Hey I am a virtual assistant calling from Retell Hospital."

general_prompt

string | null

General prompt appended to system prompt no matter what state the agent is in.

System prompt (with state) = general prompt + state prompt.
System prompt (no state) = general prompt.

Example:

"You are ..."

voice_prompt

string | null

Prompt for the voice model when model_config.type is duplex, at most 15,000 tokens. Required for duplex, where general_prompt is the backend's prompt. Kept when you switch models.

Example:

"You are a friendly voice assistant for ..."

general_tools

object[] | null

A list of tools the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use.

Tools of LLM (with state) = general tools + state tools + state transitions
Tools of LLM (no state) = general tools

Show child attributes

Example:

[
  {
    "type": "end_call",
    "name": "end_call",
    "description": "End the call with user."
  }
]

states

object[] | null

deprecated

States of the LLM. This is to help reduce prompt length and tool choices when the call can be broken into distinct states. With shorter prompts and less tools, the LLM can better focus and follow the rules, minimizing hallucination. If this field is not set, the agent would only have general prompt and general tools (essentially one state).

Show child attributes

Example:

[
  {
    "name": "information_collection",
    "state_prompt": "You will follow the steps below to collect information...",
    "edges": [
      {
        "destination_state_name": "appointment_booking",
        "description": "Transition to book an appointment."
      }
    ],
    "tools": [
      {
        "type": "transfer_call",
        "name": "transfer_to_support",
        "description": "Transfer to the support team.",
        "transfer_destination": {
          "type": "predefined",
          "number": "16175551212",
          "ignore_e164_validation": false
        },
        "transfer_option": {
          "type": "cold_transfer",
          "show_transferee_as_caller": false
        }
      }
    ]
  },
  {
    "name": "appointment_booking",
    "state_prompt": "You will follow the steps below to book an appointment...",
    "tools": [
      {
        "type": "custom",
        "name": "book_appointment",
        "description": "Book an annual check up.",
        "url": "https://api.example.com/book-appointment",
        "method": "POST"
      }
    ]
  }
]

starting_state

string | null

Name of the starting state. Required if states is not empty.

Example:

"information_collection"

default_dynamic_variables

object | null

Default dynamic variables represented as key-value pairs of strings. These are injected into your Retell LLM prompt and tool description when specific values are not provided in a request. Only applicable for Retell LLM.

Show child attributes

Example:

{ "customer_name": "John Doe" }

mcps

object[] | null

A list of MCPs to use for this LLM.

Show child attributes

is_transfer_llm

boolean | null

Whether this Retell LLM is used for warm transfer. Can only be set at creation, and is ignored on update.

Example:

false

Response

Successfully created a new Retell LLM Response Engine.

Override properties for Retell LLM configuration in agent override requests.

llm_id

string

required

Unique id of Retell LLM Response Engine.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

last_modification_timestamp

integer

required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example:

1703413636133

version

integer

Version of the Retell LLM Response Engine.

Example:

0

is_published

boolean

Whether the Retell LLM Response Engine is published.

Example:

false

model_config

object

Option 1
Option 2
Option 3

Show child attributes

backup_model

object

deprecated

Backup models are supported only for call agents. Response engines with a backup model cannot be used by chat agents.

Option 1
Option 2
Option 3
Option 4

Show child attributes

model

enum<string> | null

deprecated

Deprecated, use model_config.primary. Ignored when model_config is set.

Available options:

gpt-4.1,

gpt-4.1-mini,

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-5.1,

gpt-5.2,

gpt-5.4,

gpt-5.4-mini,

gpt-5.4-nano,

gpt-5.5,

gpt-5.6-terra,

gpt-5.6-luna,

gpt-6-astra,

gpt-6-sol,

gpt-6.1-sol,

gpt-6.1-terra,

gpt-6-luna,

tell-1,

claude-4.6-sonnet,

claude-5-opus,

claude-5.5-opus,

claude-5-sonnet,

claude-5.5-sonnet,

claude-5.5-haiku,

claude-4.5-haiku,

gemini-3.0-flash,

gemini-3.1-flash-lite,

gemini-3.5-flash,

gemini-3.5-flash-lite,

gemini-3.6-flash,

gemini-3.7-flash,

gemini-3.8-flash,

gemini-4-hydrogen,

gemini-4-carbon,

gemini-4-argon,

null

Example:

"gpt-5.6-terra"

s2s_model

enum<string> | null

deprecated

Deprecated, use model_config with type s2s. Ignored when model_config is set.

Available options:

gpt-realtime-2.1,

gpt-realtime-2.1-mini,

gpt-realtime-2,

gpt-realtime-1.5,

gpt-realtime,

gpt-realtime-mini,

grok-voice-3.0,

null

Example:

"gpt-realtime-1.5"

model_temperature

number

deprecated

Deprecated, use model_config.temperature. Ignored when model_config is set.

Example:

0

model_high_priority

boolean | null

deprecated

Deprecated, use model_config.primary.tier fast. Ignored when model_config is set.

Example:

true

model_ultrafast

boolean | null

deprecated

Deprecated, use model_config.primary.tier ultrafast. Ignored when model_config is set.

Example:

true

knowledge_base_ids

string[] | null

A list of knowledge base ids to use for this resource.

kb_config

object | null

Knowledge base configuration for RAG retrieval.

Show child attributes

start_speaker

enum<string>

The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.

Available options:

user,

agent

begin_after_user_silence_ms

integer | null

Example:

2000

begin_message

string | null

First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.

Example:

"Hey I am a virtual assistant calling from Retell Hospital."

general_prompt

string | null

General prompt appended to system prompt no matter what state the agent is in.

System prompt (with state) = general prompt + state prompt.
System prompt (no state) = general prompt.

Example:

"You are ..."

voice_prompt

string | null

Prompt for the voice model when model_config.type is duplex, at most 15,000 tokens. Required for duplex, where general_prompt is the backend's prompt. Kept when you switch models.

Example:

"You are a friendly voice assistant for ..."

general_tools

object[] | null

Tools of LLM (with state) = general tools + state tools + state transitions
Tools of LLM (no state) = general tools

Show child attributes

Example:

[
  {
    "type": "end_call",
    "name": "end_call",
    "description": "End the call with user."
  }
]

states

object[] | null

deprecated

Show child attributes

Example:

[
  {
    "name": "information_collection",
    "state_prompt": "You will follow the steps below to collect information...",
    "edges": [
      {
        "destination_state_name": "appointment_booking",
        "description": "Transition to book an appointment."
      }
    ],
    "tools": [
      {
        "type": "transfer_call",
        "name": "transfer_to_support",
        "description": "Transfer to the support team.",
        "transfer_destination": {
          "type": "predefined",
          "number": "16175551212",
          "ignore_e164_validation": false
        },
        "transfer_option": {
          "type": "cold_transfer",
          "show_transferee_as_caller": false
        }
      }
    ]
  },
  {
    "name": "appointment_booking",
    "state_prompt": "You will follow the steps below to book an appointment...",
    "tools": [
      {
        "type": "custom",
        "name": "book_appointment",
        "description": "Book an annual check up.",
        "url": "https://api.example.com/book-appointment",
        "method": "POST"
      }
    ]
  }
]

starting_state

string | null

Name of the starting state. Required if states is not empty.

Example:

"information_collection"

default_dynamic_variables

object | null

Show child attributes

Example:

{ "customer_name": "John Doe" }

mcps

object[] | null

A list of MCPs to use for this LLM.

Show child attributes

is_transfer_llm

boolean | null

Whether this Retell LLM is used for warm transfer. Can only be set at creation, and is ignored on update.

Example:

false

⌘I

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const llmResponse = await client.llm.create();

console.log(llmResponse.llm_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
llm_response = client.llm.create()
print(llm_response.llm_id)

curl --request POST \
  --url https://api.retellai.com/create-retell-llm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_config": {
    "type": "cascading",
    "backup": {
      "kick_in_timeout_ms": 30150
    },
    "temperature": 0
  },
  "backup_model": {
    "type": "cascading",
    "high_priority": true,
    "ultrafast": true,
    "backup_kick_in_timeout": 30150
  },
  "model": "gpt-5.6-terra",
  "s2s_model": "gpt-realtime-1.5",
  "model_temperature": 0,
  "model_high_priority": true,
  "model_ultrafast": true,
  "knowledge_base_ids": [
    "<string>"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "begin_after_user_silence_ms": 2000,
  "begin_message": "Hey I am a virtual assistant calling from Retell Hospital.",
  "general_prompt": "You are ...",
  "voice_prompt": "You are a friendly voice assistant for ...",
  "general_tools": [
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call with user."
    }
  ],
  "states": [
    {
      "name": "information_collection",
      "state_prompt": "You will follow the steps below to collect information...",
      "edges": [
        {
          "destination_state_name": "appointment_booking",
          "description": "Transition to book an appointment."
        }
      ],
      "tools": [
        {
          "type": "transfer_call",
          "name": "transfer_to_support",
          "description": "Transfer to the support team.",
          "transfer_destination": {
            "type": "predefined",
            "number": "16175551212",
            "ignore_e164_validation": false
          },
          "transfer_option": {
            "type": "cold_transfer",
            "show_transferee_as_caller": false
          }
        }
      ]
    },
    {
      "name": "appointment_booking",
      "state_prompt": "You will follow the steps below to book an appointment...",
      "tools": [
        {
          "type": "custom",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "url": "https://api.example.com/book-appointment",
          "method": "POST"
        }
      ]
    }
  ],
  "starting_state": "information_collection",
  "default_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "is_transfer_llm": false
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/create-retell-llm",
  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([
    'model_config' => [
        'type' => 'cascading',
        'backup' => [
                'kick_in_timeout_ms' => 30150
        ],
        'temperature' => 0
    ],
    'backup_model' => [
        'type' => 'cascading',
        'high_priority' => true,
        'ultrafast' => true,
        'backup_kick_in_timeout' => 30150
    ],
    'model' => 'gpt-5.6-terra',
    's2s_model' => 'gpt-realtime-1.5',
    'model_temperature' => 0,
    'model_high_priority' => true,
    'model_ultrafast' => true,
    'knowledge_base_ids' => [
        '<string>'
    ],
    'kb_config' => [
        'top_k' => 3,
        'filter_score' => 0.6
    ],
    'begin_after_user_silence_ms' => 2000,
    'begin_message' => 'Hey I am a virtual assistant calling from Retell Hospital.',
    'general_prompt' => 'You are ...',
    'voice_prompt' => 'You are a friendly voice assistant for ...',
    'general_tools' => [
        [
                'type' => 'end_call',
                'name' => 'end_call',
                'description' => 'End the call with user.'
        ]
    ],
    'states' => [
        [
                'name' => 'information_collection',
                'state_prompt' => 'You will follow the steps below to collect information...',
                'edges' => [
                                [
                                                                'destination_state_name' => 'appointment_booking',
                                                                'description' => 'Transition to book an appointment.'
                                ]
                ],
                'tools' => [
                                [
                                                                'type' => 'transfer_call',
                                                                'name' => 'transfer_to_support',
                                                                'description' => 'Transfer to the support team.',
                                                                'transfer_destination' => [
                                                                                                                                'type' => 'predefined',
                                                                                                                                'number' => '16175551212',
                                                                                                                                'ignore_e164_validation' => false
                                                                ],
                                                                'transfer_option' => [
                                                                                                                                'type' => 'cold_transfer',
                                                                                                                                'show_transferee_as_caller' => false
                                                                ]
                                ]
                ]
        ],
        [
                'name' => 'appointment_booking',
                'state_prompt' => 'You will follow the steps below to book an appointment...',
                'tools' => [
                                [
                                                                'type' => 'custom',
                                                                'name' => 'book_appointment',
                                                                'description' => 'Book an annual check up.',
                                                                'url' => 'https://api.example.com/book-appointment',
                                                                'method' => 'POST'
                                ]
                ]
        ]
    ],
    'starting_state' => 'information_collection',
    'default_dynamic_variables' => [
        'customer_name' => 'John Doe'
    ],
    'mcps' => [
        [
                'name' => '<string>',
                'url' => '<string>',
                'headers' => [
                                'Authorization' => 'Bearer 1234567890'
                ],
                'query_params' => [
                                'index' => '1',
                                'key' => 'value'
                ],
                'timeout_ms' => 123
        ]
    ],
    'is_transfer_llm' => false
  ]),
  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.retellai.com/create-retell-llm"

	payload := strings.NewReader("{\n  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\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.retellai.com/create-retell-llm")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/create-retell-llm")

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  \"model_config\": {\n    \"type\": \"cascading\",\n    \"backup\": {\n      \"kick_in_timeout_ms\": 30150\n    },\n    \"temperature\": 0\n  },\n  \"backup_model\": {\n    \"type\": \"cascading\",\n    \"high_priority\": true,\n    \"ultrafast\": true,\n    \"backup_kick_in_timeout\": 30150\n  },\n  \"model\": \"gpt-5.6-terra\",\n  \"s2s_model\": \"gpt-realtime-1.5\",\n  \"model_temperature\": 0,\n  \"model_high_priority\": true,\n  \"model_ultrafast\": true,\n  \"knowledge_base_ids\": [\n    \"<string>\"\n  ],\n  \"kb_config\": {\n    \"top_k\": 3,\n    \"filter_score\": 0.6\n  },\n  \"begin_after_user_silence_ms\": 2000,\n  \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\",\n  \"general_prompt\": \"You are ...\",\n  \"voice_prompt\": \"You are a friendly voice assistant for ...\",\n  \"general_tools\": [\n    {\n      \"type\": \"end_call\",\n      \"name\": \"end_call\",\n      \"description\": \"End the call with user.\"\n    }\n  ],\n  \"states\": [\n    {\n      \"name\": \"information_collection\",\n      \"state_prompt\": \"You will follow the steps below to collect information...\",\n      \"edges\": [\n        {\n          \"destination_state_name\": \"appointment_booking\",\n          \"description\": \"Transition to book an appointment.\"\n        }\n      ],\n      \"tools\": [\n        {\n          \"type\": \"transfer_call\",\n          \"name\": \"transfer_to_support\",\n          \"description\": \"Transfer to the support team.\",\n          \"transfer_destination\": {\n            \"type\": \"predefined\",\n            \"number\": \"16175551212\",\n            \"ignore_e164_validation\": false\n          },\n          \"transfer_option\": {\n            \"type\": \"cold_transfer\",\n            \"show_transferee_as_caller\": false\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"appointment_booking\",\n      \"state_prompt\": \"You will follow the steps below to book an appointment...\",\n      \"tools\": [\n        {\n          \"type\": \"custom\",\n          \"name\": \"book_appointment\",\n          \"description\": \"Book an annual check up.\",\n          \"url\": \"https://api.example.com/book-appointment\",\n          \"method\": \"POST\"\n        }\n      ]\n    }\n  ],\n  \"starting_state\": \"information_collection\",\n  \"default_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"mcps\": [\n    {\n      \"name\": \"<string>\",\n      \"url\": \"<string>\",\n      \"headers\": {\n        \"Authorization\": \"Bearer 1234567890\"\n      },\n      \"query_params\": {\n        \"index\": \"1\",\n        \"key\": \"value\"\n      },\n      \"timeout_ms\": 123\n    }\n  ],\n  \"is_transfer_llm\": false\n}"

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

{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "last_modification_timestamp": 1703413636133,
  "version": 0,
  "is_published": false,
  "model_config": {
    "type": "cascading",
    "primary": {
      "model": "gpt-4.1",
      "tier": "standard"
    },
    "backup": {
      "model": "gpt-4.1",
      "tier": "standard",
      "kick_in_timeout_ms": 30150
    },
    "temperature": 0
  },
  "backup_model": {
    "type": "cascading",
    "model": "gpt-4.1",
    "high_priority": true,
    "ultrafast": true,
    "backup_kick_in_timeout": 30150
  },
  "model": "gpt-5.6-terra",
  "s2s_model": "gpt-realtime-1.5",
  "model_temperature": 0,
  "model_high_priority": true,
  "model_ultrafast": true,
  "knowledge_base_ids": [
    "<string>"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "start_speaker": "user",
  "begin_after_user_silence_ms": 2000,
  "begin_message": "Hey I am a virtual assistant calling from Retell Hospital.",
  "general_prompt": "You are ...",
  "voice_prompt": "You are a friendly voice assistant for ...",
  "general_tools": [
    {
      "type": "end_call",
      "name": "end_call",
      "description": "End the call with user."
    }
  ],
  "states": [
    {
      "name": "information_collection",
      "state_prompt": "You will follow the steps below to collect information...",
      "edges": [
        {
          "destination_state_name": "appointment_booking",
          "description": "Transition to book an appointment."
        }
      ],
      "tools": [
        {
          "type": "transfer_call",
          "name": "transfer_to_support",
          "description": "Transfer to the support team.",
          "transfer_destination": {
            "type": "predefined",
            "number": "16175551212",
            "ignore_e164_validation": false
          },
          "transfer_option": {
            "type": "cold_transfer",
            "show_transferee_as_caller": false
          }
        }
      ]
    },
    {
      "name": "appointment_booking",
      "state_prompt": "You will follow the steps below to book an appointment...",
      "tools": [
        {
          "type": "custom",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "url": "https://api.example.com/book-appointment",
          "method": "POST"
        }
      ]
    }
  ],
  "starting_state": "information_collection",
  "default_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "is_transfer_llm": false
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Authorizations

Body

Response