Skip to main content
PATCH
JavaScript

Authorizations

Authorization
string
header
required

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

Path Parameters

llm_id
string
required

Unique id of the Retell LLM Response Engine to be updated.

Example:

"16b980523634a6dc504898cda492e939"

Query Parameters

version
integer

Optional version of the API to use for this request. Default to latest version.

Example:

1

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, and backup cannot be removed.

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-luna,
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-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,
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

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 | null

Knowledge base configuration for RAG retrieval.

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 for the LLM to use.

  • Tools of LLM (with state) = general tools + state tools + state transitions
  • Tools of LLM (no state) = general tools
Example:
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).

Example:
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.

Example:
mcps
object[] | null

A list of MCPs to use for this LLM.

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 updated an 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

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, and backup cannot be removed.

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-luna,
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-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,
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

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 | null

Knowledge base configuration for RAG retrieval.

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 for the LLM to use.

  • Tools of LLM (with state) = general tools + state tools + state transitions
  • Tools of LLM (no state) = general tools
Example:
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).

Example:
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.

Example:
mcps
object[] | null

A list of MCPs to use for this LLM.

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