Create Retell LLM

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

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

console.log(llmResponse.llm_id);

{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 1,
  "is_published": false,
  "model": "gpt-4.1",
  "s2s_model": "gpt-4o-realtime",
  "model_temperature": 0,
  "model_high_priority": true,
  "tool_call_strict_mode": 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 ...",
  "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": "book_appointment_cal",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "cal_api_key": "cal_live_xxxxxxxxxxxx",
          "event_type_id": 60444,
          "timezone": "America/Los_Angeles"
        }
      ]
    }
  ],
  "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
    }
  ],
  "last_modification_timestamp": 1703413636133
}

POST

create-retell-llm

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

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

console.log(llmResponse.llm_id);

{
  "llm_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 1,
  "is_published": false,
  "model": "gpt-4.1",
  "s2s_model": "gpt-4o-realtime",
  "model_temperature": 0,
  "model_high_priority": true,
  "tool_call_strict_mode": 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 ...",
  "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": "book_appointment_cal",
          "name": "book_appointment",
          "description": "Book an annual check up.",
          "cal_api_key": "cal_live_xxxxxxxxxxxx",
          "event_type_id": 60444,
          "timezone": "America/Los_Angeles"
        }
      ]
    }
  ],
  "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
    }
  ],
  "last_modification_timestamp": 1703413636133
}

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

enum<string> | null

Select the underlying text LLM. If not set, would default to gpt-4.1.

Available options:

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-4o,

gpt-4o-mini,

gpt-4.1,

gpt-4.1-mini,

gpt-4.1-nano,

claude-3.7-sonnet,

claude-3.5-haiku,

gemini-2.0-flash,

gemini-2.0-flash-lite,

gemini-2.5-flash,

gemini-2.5-flash-lite

Example:

"gpt-4.1"

s2s_model

enum<string> | null

Select the underlying speech to speech model. Can only set this or model, not both.

Available options:

gpt-4o-realtime,

gpt-4o-mini-realtime,

gpt-realtime

Example:

"gpt-4o-realtime"

model_temperature

number

If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended.

Example:

0

model_high_priority

boolean | null

If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.

Example:

true

tool_call_strict_mode

boolean | null

Whether to use strict mode for tool calls. Only applicable when using certain supported models.

Example:

true

knowledge_base_ids

string[] | null

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

kb_config

object

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 ..."

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 (last option) for the LLM to use.

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

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
Option 9
Option 10

Show child attributes

Example:

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

states

object[] | null

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": "book_appointment_cal",
        "name": "book_appointment",
        "description": "Book an annual check up.",
        "cal_api_key": "cal_live_xxxxxxxxxxxx",
        "event_type_id": 60444,
        "timezone": "America/Los_Angeles"
      }
    ]
  }
]

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" }

version

integer | null

The version of the LLM.

Example:

1

mcps

object[] | null

A list of MCPs to use for this LLM.

Show child attributes

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. The version of the LLM.

Example:

1

is_published

boolean

Whether the Retell LLM Response Engine is published.

Example:

false

model

enum<string> | null

Select the underlying text LLM. If not set, would default to gpt-4.1.

Available options:

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-4o,

gpt-4o-mini,

gpt-4.1,

gpt-4.1-mini,

gpt-4.1-nano,

claude-3.7-sonnet,

claude-3.5-haiku,

gemini-2.0-flash,

gemini-2.0-flash-lite,

gemini-2.5-flash,

gemini-2.5-flash-lite

Example:

"gpt-4.1"

s2s_model

enum<string> | null

Select the underlying speech to speech model. Can only set this or model, not both.

Available options:

gpt-4o-realtime,

gpt-4o-mini-realtime,

gpt-realtime

Example:

"gpt-4o-realtime"

model_temperature

number

Example:

0

model_high_priority

boolean | null

If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.

Example:

true

tool_call_strict_mode

boolean | null

Whether to use strict mode for tool calls. Only applicable when using certain supported models.

Example:

true

knowledge_base_ids

string[] | null

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

kb_config

object

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 ..."

general_tools

object[] | null

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

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
Option 9
Option 10

Show child attributes

Example:

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

states

object[] | null

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": "book_appointment_cal",
        "name": "book_appointment",
        "description": "Book an annual check up.",
        "cal_api_key": "cal_live_xxxxxxxxxxxx",
        "event_type_id": 60444,
        "timezone": "America/Los_Angeles"
      }
    ]
  }
]

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

Get MCP Tools Get Retell LLM

⌘I

Call (V2)

Chat

Phone Number

Agent

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

Conversation Flow Response Engine (for conversation flow agent)

Knowledge Base

Voice

Batch call

Tests

Account

Custom Telephony

Custom LLM

Authorizations

Body

Response