Retell AI Create Retell Llm API
The Create Retell Llm API from Retell AI — 1 operation(s) for create retell llm.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/retell-ai-create-retell-llm-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
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:
PostCallAnalysisSetting:
type: string
enum:
- both_agents
- only_destination_agent
CustomTool:
type: object
properties:
type:
type: string
enum:
- custom
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).
url:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
description:
type: string
description: Describes what this tool does and when to call this tool.
method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
description: Method to use for the request, default to POST.
headers:
type: object
additionalProperties:
type: string
example:
Authorization: Bearer 1234567890
description: Headers to add to the request.
query_params:
type: object
additionalProperties:
type: string
example:
page: '1'
sort: asc
description: Query parameters to append to the request URL.
parameters:
$ref: '#/components/schemas/ToolParameter'
response_variables:
type: object
additionalProperties:
type: string
example:
user_name: data.user.name
description: A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
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".
timeout_ms:
type: integer
description: The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
args_at_root:
type: boolean
description: If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
enable_typing_sound:
type: boolean
description: If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
required:
- type
- name
- url
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
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
AnalysisData:
oneOf:
- $ref: '#/components/schemas/StringAnalysisData'
- $ref: '#/components/schemas/EnumAnalysisData'
- $ref: '#/components/schemas/BooleanAnalysisData'
- $ref: '#/components/schemas/NumberAnalysisData'
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
StateEdge:
type: object
required:
- destination_state_name
- description
properties:
destination_state_name:
type: string
description: The destination state name when going through transition of state via this edge. State transition internally is implemented as a tool call of LLM, and a tool call with name "transition_to_{destination_state_name}" will get created. Feel free to reference it inside the prompt.
description:
type: string
description: Describes what's the transition and at what time / criteria should this transition happen.
parameters:
$ref: '#/components/schemas/ToolParameter'
description: Describes what parameters you want to extract out when the transition changes. The parameters extracted here can be referenced in prompts & function descriptions of later states via dynamic variables. 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.
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
WarmTransferPrompt:
type: object
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
example: Summarize the call in one sentence for the warn handoff.
description: The prompt to be used for warm handoff. Can contain dynamic variables.
EnumAnalysisData:
type: object
required:
- type
- name
- description
- choices
properties:
type:
type: string
enum:
- enum
description: Type of the variable to extract.
example: enum
name:
type: string
description: Name of the variable.
example: product_rating
minLength: 1
description:
type: string
description: Description of the variable.
example: Rating of the product.
choices:
type: array
items:
type: string
description: The possible values of the variable, must be non empty array.
example:
- good
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
NumberAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- number
description: Type of the variable to extract.
example: number
name:
type: string
description: Name of the variable.
example: order_count
minLength: 1
description:
type: string
description: Description of the variable.
example: How many the customer intend to order.
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
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
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
AgentSwapWebhookSetting:
type: string
enum:
- both_agents
- only_destination_agent
- only_source_agent
SmsContent:
oneOf:
- $ref: '#/components/schemas/SmsContentPredefined'
- $ref: '#/components/schemas/SmsContentInferred'
- $ref: '#/components/schemas/SmsContentTemplate'
EndCallTool:
type: object
properties:
type:
type: string
enum:
- end_call
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.
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 ending 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
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'
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.
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
SmsContentTemplate:
type: object
required:
- type
- template
properties:
type:
type: string
enum:
- template
template:
type: string
enum:
- info_collection
description: The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user.
AgentSwapTool:
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:
- agent_swap
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
agent_id:
type: string
minLength: 1
description: The id of the agent to swap to.
agent_version:
$ref: '#/components/schemas/AgentVersionReference'
description: The version of the agent to swap to. If not specified, will use the latest version.
speak_during_execution:
type: boolean
execution_message_description:
type: string
description: The message for the agent to speak when executing agent swap.
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".
post_call_analysis_setting:
$ref: '#/components/schemas/PostCallAnalysisSetting'
description: Post call analysis setting for the agent swap.
webhook_setting:
$ref: '#/components/schemas/AgentSwapWebhookSetting'
description: Webhook setting for the agent swap, defaults to only source.
keep_current_voice:
type: boolean
description: If true, keep the current voice when swapping agents. Defaults to false.
keep_current_language:
type: boolean
description: If true, keep the current language when swapping agents. Defaults to false.
required:
- type
- name
- agent_id
- post_call_analysis_setting
StringAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- string
description: Type of the variable to extract.
example: string
name:
type: string
description: Name of the variable.
example: customer_name
minLength: 1
description:
type: string
description: Description of the variable.
example: The name of the customer.
examples:
type: array
items:
type: string
description: Examples of the variable value to teach model the style and syntax.
example:
- John Doe
- Jane Smith
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
BooleanAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- boolean
description: Type of the variable to extract.
example: boolean
name:
type: string
description: Name of the variable.
example: is_converted
minLength: 1
description:
type: string
description: Description of the variable.
example: Whether the customer converted.
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
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
'
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
SmsContentPredefined:
type: object
properties:
type:
type: string
enum:
- predefined
content:
type: string
description: The static message to be sent in the SMS. Can contain dynamic variables.
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
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 nu
# --- 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