Retell AI Create Retell Llm API
The Create Retell Llm API from Retell AI — 1 operation(s) for create retell llm.
OpenAPI Specification
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice Create Retell Llm API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: Create Retell Llm
paths:
/create-retell-llm:
post:
description: Create a new Retell LLM Response Engine that can be attached to an agent. This is used to generate response output for the agent.
operationId: createRetellLLM
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetellLlmRequest'
responses:
'201':
description: Successfully created a new Retell LLM Response Engine.
content:
application/json:
schema:
$ref: '#/components/schemas/RetellLLMResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- Create Retell Llm
components:
schemas:
State:
type: object
required:
- name
properties:
name:
example: information_collection
type: string
description: Name of the state, must be unique for each state. Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
state_prompt:
example: '## Task
You will follow the steps below...'
type: string
description: 'Prompt of the state, will be appended to the system prompt of LLM.
- System prompt = general prompt + state prompt.
'
edges:
type: array
items:
$ref: '#/components/schemas/StateEdge'
description: Edges of the state define how and what state can be reached from this state.
tools:
type: array
items:
$ref: '#/components/schemas/Tool'
description: 'A list of tools specific to this state 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 = general tools + state tools + state transitions
'
RetellLLMResponse:
allOf:
- type: object
required:
- llm_id
properties:
llm_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Unique id of Retell LLM Response Engine.
version:
type: integer
example: 0
description: Version of the Retell LLM Response Engine.
is_published:
type: boolean
example: false
description: Whether the Retell LLM Response Engine is published.
- $ref: '#/components/schemas/RetellLlmRequest'
- type: object
required:
- last_modification_timestamp
properties:
last_modification_timestamp:
type: integer
example: 1703413636133
description: Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.
TransferDestinationPredefined:
type: object
properties:
type:
type: string
enum:
- predefined
description: The type of transfer destination.
number:
type: string
description: The number to transfer to in E.164 format or a dynamic variable like {{transfer_number}}.
extension:
type: string
description: Extension digits to dial after the main number connects. Sent via DTMF. Allow digits, '*', '#', or a dynamic variable like {{extension}}.
example: 123*456#
required:
- type
- number
ToolParameter:
type: object
description: The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list.
required:
- type
- properties
properties:
type:
type: string
enum:
- object
description: Type must be "object" for a JSON Schema object.
properties:
type: object
additionalProperties: {}
description: The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property.
required:
type: array
items:
type: string
description: List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties.
Tool:
oneOf:
- $ref: '#/components/schemas/EndCallTool'
- $ref: '#/components/schemas/TransferCallTool'
- $ref: '#/components/schemas/CheckAvailabilityCalTool'
- $ref: '#/components/schemas/BookAppointmentCalTool'
- $ref: '#/components/schemas/AgentSwapTool'
- $ref: '#/components/schemas/PressDigitTool'
- $ref: '#/components/schemas/SendSMSTool'
- $ref: '#/components/schemas/CustomTool'
- $ref: '#/components/schemas/CodeTool'
- $ref: '#/components/schemas/ExtractDynamicVariableTool'
- $ref: '#/components/schemas/BridgeTransferTool'
- $ref: '#/components/schemas/CancelTransferTool'
- $ref: '#/components/schemas/MCPTool'
TransferOptionColdTransfer:
type: object
title: Cold Transfer
properties:
type:
type: string
enum:
- cold_transfer
description: The type of the transfer.
show_transferee_as_caller:
type: boolean
description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring. Requires the telephony side to support caller id override. Retell Twilio numbers support this option. This parameter takes effect only when `cold_transfer_mode` is set to `sip_invite`. When using `sip_refer`, this option is not available. Retell Twilio numbers always use user's number as the caller id when using `sip refer` cold transfer mode.
cold_transfer_mode:
type: string
enum:
- sip_refer
- sip_invite
description: The mode of the cold transfer. If set to `sip_refer`, will use SIP REFER to transfer the call. If set to `sip_invite`, will use SIP INVITE to transfer the call.
default: sip_invite
transfer_ring_duration_ms:
type: integer
minimum: 5000
maximum: 90000
description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
required:
- type
TransferDestination:
oneOf:
- $ref: '#/components/schemas/TransferDestinationPredefined'
- $ref: '#/components/schemas/TransferDestinationInferred'
MCP:
type: object
properties:
name:
type: string
url:
type: string
description: The URL of the MCP server.
headers:
type: object
additionalProperties:
type: string
example:
Authorization: Bearer 1234567890
description: Headers to add to the MCP connection request.
query_params:
type: object
additionalProperties:
type: string
example:
index: '1'
key: value
description: Query parameters to append to the MCP connection request URL.
timeout_ms:
type: integer
description: Maximum time to wait for a connection to be established (in milliseconds). Default to 120,000 ms (2 minutes).
required:
- name
- url
WarmTransferStaticMessage:
type: object
properties:
type:
type: string
enum:
- static_message
message:
type: string
example: You can take it from here.
description: The static message to be used for warm handoff. Can contain dynamic variables.
AgentSwapWebhookSetting:
type: string
enum:
- both_agents
- only_destination_agent
- only_source_agent
TransferDestinationInferred:
type: object
properties:
type:
type: string
enum:
- inferred
description: The type of transfer destination.
prompt:
type: string
description: The prompt to be used to help infer the transfer destination. The model will take the global prompt, the call transcript, and this prompt together to deduce the right number to transfer to. Can contain dynamic variables.
required:
- type
- prompt
CodeTool:
type: object
properties:
type:
type: string
enum:
- code
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what this tool does and when to call this tool.
code:
type: string
maxLength: 20000
description: JavaScript code to execute in the sandbox.
timeout_ms:
type: integer
minimum: 5000
maximum: 60000
description: The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s).
response_variables:
type: object
additionalProperties:
type: string
example:
order_id: data.order.id
description: A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables.
speak_during_execution:
type: boolean
description: Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool.
speak_after_execution:
type: boolean
default: true
description: Determines whether the agent would call LLM another time and speak when the result of function is obtained.
execution_message_description:
type: string
description: The description for the sentence agent say during execution. Only applicable when speak_during_execution is true.
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
enable_typing_sound:
type: boolean
description: If true, play a typing sound on the agent audio track while this tool is executing.
required:
- type
- name
- code
CheckAvailabilityCalTool:
type: object
properties:
type:
type: string
enum:
- check_availability_cal
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
cal_api_key:
type: string
description: Cal.com Api key that have access to the cal.com event you want to check availability for.
event_type_id:
oneOf:
- type: number
- type: string
description: Cal.com event type id number for the cal.com event you want to check availability for. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
timezone:
type: string
description: Timezone to be used when checking availability, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
required:
- type
- name
- cal_api_key
- event_type_id
SendSMSTool:
type: object
properties:
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
type:
type: string
enum:
- send_sms
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
speak_during_execution:
type: boolean
description: If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools).
execution_message_description:
type: string
description: Describes what to say before sending the SMS. Only applicable when speak_during_execution is true.
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
sms_content:
$ref: '#/components/schemas/SmsContent'
required:
- type
- name
- sms_content
SmsContentInferred:
type: object
properties:
type:
type: string
enum:
- inferred
prompt:
type: string
description: The prompt to be used to help infer the SMS content. The model will take the global prompt, the call transcript, and this prompt together to deduce the right message to send. Can contain dynamic variables.
BookAppointmentCalTool:
type: object
properties:
type:
type: string
enum:
- book_appointment_cal
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
cal_api_key:
type: string
description: Cal.com Api key that have access to the cal.com event you want to book appointment.
event_type_id:
oneOf:
- type: number
- type: string
description: Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime.
timezone:
type: string
description: Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers.
required:
- type
- name
- cal_api_key
- event_type_id
TransferOptionWarmTransfer:
type: object
title: Warm Transfer
properties:
type:
type: string
enum:
- warm_transfer
description: The type of the transfer.
show_transferee_as_caller:
type: boolean
description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
agent_detection_timeout_ms:
type: number
description: The time to wait before considering transfer fails.
transfer_ring_duration_ms:
type: integer
minimum: 5000
maximum: 90000
description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
on_hold_music:
type: string
enum:
- none
- relaxing_sound
- uplifting_beats
- ringtone
description: The music to play while the caller is being transferred.
public_handoff_option:
type: object
oneOf:
- $ref: '#/components/schemas/WarmTransferPrompt'
- $ref: '#/components/schemas/WarmTransferStaticMessage'
description: If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
private_handoff_option:
type: object
oneOf:
- $ref: '#/components/schemas/WarmTransferPrompt'
- $ref: '#/components/schemas/WarmTransferStaticMessage'
description: If set, when transfer is connected, will say the handoff message only to the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
ivr_option:
type: object
$ref: '#/components/schemas/WarmTransferPrompt'
description: IVR navigation option to run when doing human detection. This prompt will guide the AI on how to navigate the IVR system.
opt_out_human_detection:
type: boolean
description: If set to true, will not perform human detection for the transfer. Default to false.
enable_bridge_audio_cue:
type: boolean
description: Whether to play an audio cue when bridging the call. Defaults to true.
default: true
required:
- type
CancelTransferTool:
type: object
properties:
type:
type: string
enum:
- cancel_transfer
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does. This tool is only available to transfer agents (agents with isTransferAgent set to true) in agentic warm transfer mode. When invoked, it cancels the transfer, returns the original caller to the main agent, and ends the transfer agent call.
speak_during_execution:
type: boolean
description: If true, will speak during execution.
execution_message_description:
type: string
description: Describes what to say to user when cancelling the transfer. Only applicable when speak_during_execution is true.
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
required:
- type
- name
MCPTool:
type: object
properties:
type:
type: string
enum:
- mcp
mcp_id:
type: string
description: Unique id of the MCP.
name:
type: string
description: Name of the MCP tool.
description:
type: string
description: Description of the MCP tool.
input_schema:
type: object
additionalProperties:
type: string
description: The input schema of the MCP tool.
response_variables:
type: object
additionalProperties:
type: string
description: Response variables to add to dynamic variables, key is the variable name, value is the path to the variable in the response
speak_during_execution:
type: boolean
description: Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
speak_after_execution:
type: boolean
description: Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
execution_message_description:
type: string
description: The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
enable_typing_sound:
type: boolean
description: If true, play a typing sound on the agent audio track while this MCP tool is executing.
required:
- type
- name
- description
ExtractDynamicVariableTool:
type: object
properties:
type:
type: string
enum:
- extract_dynamic_variable
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
variables:
type: array
items:
$ref: '#/components/schemas/AnalysisData'
description: The variables to be extracted.
required:
- type
- name
- variables
- description
TransferCallTool:
type: object
properties:
type:
type: string
enum:
- transfer_call
name:
type: string
example: transfer_to_support
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
transfer_destination:
type: object
$ref: '#/components/schemas/TransferDestination'
ignore_e164_validation:
type: boolean
description: If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.
example: false
custom_sip_headers:
type: object
additionalProperties:
type: string
example:
X-Custom-Header: Custom Value
description: Custom SIP headers to be added to the call.
transfer_option:
type: object
$ref: '#/components/schemas/TransferOption'
speak_during_execution:
type: boolean
description: If true, will speak during execution.
execution_message_description:
type: string
description: Describes what to say to user when transferring the call. Only applicable when speak_during_execution is true.
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
required:
- type
- name
- transfer_destination
- transfer_option
SmsContent:
oneOf:
- $ref: '#/components/schemas/SmsContentPredefined'
- $ref: '#/components/schemas/SmsContentInferred'
- $ref: '#/components/schemas/SmsContentTemplate'
TransferOptionAgenticWarmTransfer:
type: object
title: Agentic Warm Transfer
properties:
type:
type: string
enum:
- agentic_warm_transfer
description: The type of the transfer.
show_transferee_as_caller:
type: boolean
description: If set to true, will show transferee (the user, not the AI agent) as caller when transferring, requires the telephony side to support caller id override. Retell Twilio numbers support this option.
on_hold_music:
type: string
enum:
- none
- relaxing_sound
- uplifting_beats
- ringtone
description: The music to play while the caller is being transferred.
transfer_ring_duration_ms:
type: integer
minimum: 5000
maximum: 90000
description: Override the ring duration for this specific transfer, in milliseconds. If not set, falls back to the agent-level `ring_duration_ms`.
public_handoff_option:
type: object
oneOf:
- $ref: '#/components/schemas/WarmTransferPrompt'
- $ref: '#/components/schemas/WarmTransferStaticMessage'
description: If set, when transfer is successful, will say the handoff message to both the transferee and the agent receiving the transfer. Can leave either a static message or a dynamic one based on prompt. Set to null to disable warm handoff.
agentic_transfer_config:
type: object
description: Configuration for agentic warm transfer. Required for agentic warm transfer.
properties:
transfer_agent:
type: object
description: The agent that will mediate the transfer decision.
properties:
agent_id:
type: string
minLength: 1
description: The agent ID of the transfer agent. This agent must have isTransferAgent set to true and should use bridge_transfer and cancel_transfer tools (for Retell LLM) or BridgeTransferNode and CancelTransferNode (for Conversation Flow).
agent_version:
type: number
description: The version of the transfer agent to use.
required:
- agent_id
- agent_version
transfer_timeout_ms:
type: number
description: The maximum time to wait for the transfer agent to make a decision, in milliseconds. Defaults to 30000 (30 seconds).
default: 30000
action_on_timeout:
type: string
enum:
- bridge_transfer
- cancel_transfer
description: The action to take when the transfer agent times out without making a decision. Defaults to cancel_transfer.
default: cancel_transfer
enable_bridge_audio_cue:
type: boolean
description: Whether to play an audio cue when bridging the call. Defaults to true.
default: true
required:
- type
- agentic_transfer_config
PressDigitTool:
type: object
properties:
type:
type: string
enum:
- press_digit
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
delay_ms:
type: integer
description: Delay in milliseconds before pressing the digit, because a lot of IVR systems speak very slowly, and a delay can make sure the agent hears the full menu. Default to 1000 ms (1s). Valid range is 0 to 5000 ms (inclusive).
required:
- type
- name
KBConfig:
type: object
properties:
top_k:
type: integer
minimum: 1
maximum: 10
example: 3
description: Max number of knowledge base chunks to retrieve
filter_score:
type: number
minimum: 0
maximum: 1
example: 0.6
description: Similarity threshold for filtering search results
RetellLlmRequest:
allOf:
- $ref: '#/components/schemas/RetellLlmOverride'
- type: object
properties:
general_prompt:
type: string
example: You are ...
description: '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.
'
nullable: true
general_tools:
type: array
items:
$ref: '#/components/schemas/Tool'
description: '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:
- type: end_call
name: end_call
description: End the call with user.
nullable: true
states:
type: array
items:
$ref: '#/components/schemas/State'
description: 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 on
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-create-retell-llm-api-openapi.yml