openapi: 3.0.3
info:
title: Retell SDK
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.
components:
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: string
description:
Authentication header containing API key (find it in dashboard). The
format is "Bearer YOUR_API_KEY"
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Invalid request format, please check API reference.
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: API key is missing or invalid.
Forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Forbidden
PaymentRequired:
description: Payment Required
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Trial has ended, please add payment method.
UnprocessableContent:
description: Unprocessable Content
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Cannot find requested asset under given api key.
TooManyRequests:
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Account rate limited, please throttle your requests.
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: An unexpected server error occurred.
NotFound:
description: Not Found
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: The requested resource was not found.
parameters:
LimitParam:
in: query
name: limit
schema:
type: integer
default: 50
maximum: 1000
description: Maximum number of items to return.
SortOrderParam:
in: query
name: sort_order
schema:
type: string
enum:
- ascending
- descending
default: descending
description: Sort order for results.
PaginationKeyParam:
in: query
name: pagination_key
schema:
type: string
description: Pagination key for fetching the next page.
schemas:
AlertMetricType:
type: string
enum:
- call_count
- concurrency_used
- call_success_rate
- negative_sentiment_rate
- custom_function_latency
- custom_function_failure_count
- transfer_call_failure_count
- qa_not_passed_count
- total_call_cost
- api_error_count
PaginatedResponseBase:
type: object
properties:
pagination_key:
type: string
description: Pagination key for the next page.
has_more:
type: boolean
description: Whether more results are available.
AlertFilter:
type: object
description: Filter criteria for alert rules
properties:
agent:
type: array
items:
$ref: "#/components/schemas/AgentFilter"
maxItems: 100
description: Agent filters, connected by OR.
disconnection_reason:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Disconnection reasons to filter on.
properties:
value:
items:
$ref: "#/components/schemas/DisconnectionReason"
custom_analysis_data:
type: array
items:
$ref: "#/components/schemas/CustomFieldFilter"
description: Filter by custom analysis data fields.
cohort_id:
allOf:
- $ref: "#/components/schemas/StringFilter"
- description:
Cohort ID to filter on (for QA Not Passed Count metrics).
status_code:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description:
API status codes to filter on (for API Error Count metrics).
properties:
value:
items:
enum:
- "400"
- "401"
- "402"
- "403"
- "404"
- "409"
- "422"
- "429"
- "500"
disconnection_reasons:
type: array
items:
$ref: "#/components/schemas/DisconnectionReason"
deprecated: true
description: "Deprecated: use 'disconnection_reason' instead."
error_code:
type: array
items:
type: string
enum:
- "400"
- "401"
- "402"
- "403"
- "404"
- "409"
- "422"
- "429"
- "500"
deprecated: true
description:
"Deprecated: use 'status_code' instead. API error codes to filter on
(for API Error Count metrics)."
AlertIncidentResponse:
type: object
properties:
alert_incident_id:
type: string
description: Unique identifier for the alert incident.
org_id:
type: string
description: Organization ID.
alert_rule_id:
type: string
description: The alert rule ID that triggered this incident.
name:
type: string
description: Name of the alert rule at the time of incident.
metric_type:
allOf:
- $ref: "#/components/schemas/AlertMetricType"
description: The metric type being monitored.
filter:
$ref: "#/components/schemas/AlertFilter"
threshold_type:
type: string
enum:
- absolute
- relative
description:
Whether threshold is absolute or relative to previous period.
threshold_value:
type: number
description: The threshold value that was configured.
comparator:
type: string
enum:
- ">"
- "<"
- ">="
- "<="
- "gt"
- "ge"
- "lt"
- "le"
description: Comparison operator for the threshold.
frequency:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
description: Evaluation frequency.
window:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
- 3d
- 7d
description: Time window for metric evaluation.
emails:
type: array
items:
type: string
description: Email addresses for notifications.
webhook_urls:
type: array
items:
type: string
description: Webhook URLs for notifications.
current_value:
type: number
description: The value that triggered the alert.
previous_value:
type: number
description: The previous period value (for relative thresholds).
triggered_timestamp:
type: number
description: Unix timestamp when the incident was triggered.
resolved_timestamp:
type: number
description: Unix timestamp when the incident was resolved.
AlertRuleRequest:
type: object
required:
- name
- metric_type
- threshold_type
- threshold_value
- comparator
- frequency
- window
properties:
name:
type: string
description: Name of the alert rule.
metric_type:
allOf:
- $ref: "#/components/schemas/AlertMetricType"
description: The metric type to monitor.
filter:
$ref: "#/components/schemas/AlertFilter"
threshold_type:
type: string
enum:
- absolute
- relative
description:
Whether threshold is absolute or relative to previous period.
threshold_value:
type: number
description: The threshold value to compare against.
comparator:
type: string
enum:
- ">"
- "<"
- ">="
- "<="
- "gt"
- "ge"
- "lt"
- "le"
description: Comparison operator for the threshold.
frequency:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
description: How often to evaluate the metric.
window:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
- 3d
- 7d
description: Time window for metric evaluation.
emails:
type: array
items:
type: string
description: Email addresses to notify when alert triggers.
webhook_urls:
type: array
items:
type: string
description: Webhook URLs to notify when alert triggers.
AlertRuleResponse:
type: object
properties:
alert_rule_id:
type: string
description: Unique identifier for the alert rule.
org_id:
type: string
description: Organization ID.
name:
type: string
description: Name of the alert rule.
metric_type:
allOf:
- $ref: "#/components/schemas/AlertMetricType"
description: The metric type being monitored.
filter:
$ref: "#/components/schemas/AlertFilter"
threshold_type:
type: string
enum:
- absolute
- relative
description:
Whether threshold is absolute or relative to previous period.
threshold_value:
type: number
description: The threshold value to compare against.
comparator:
type: string
enum:
- ">"
- "<"
- ">="
- "<="
- "gt"
- "ge"
- "lt"
- "le"
description: Comparison operator for the threshold.
frequency:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
description: How often the metric is evaluated.
window:
type: string
enum:
- 1m
- 5m
- 30m
- 1h
- 12h
- 24h
- 3d
- 7d
description: Time window for metric evaluation.
emails:
type: array
items:
type: string
description: Email addresses for notifications.
webhook_urls:
type: array
items:
type: string
description: Webhook URLs for notifications.
active:
type: boolean
description: Whether the alert rule is active.
user_modified_timestamp:
type: number
description: Unix timestamp of last modification.
AgentNaturalnessAnalysis:
type: object
required:
- details
- natural_utterance_count
- total_utterance_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/UtteranceNaturalnessIssues"
natural_utterance_count:
type: number
total_utterance_count:
type: number
AgentWeight:
type: object
required:
- agent_id
- weight
properties:
agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_version:
type: integer
example: 1
weight:
type: number
example: 0.5
minimum: 0
exclusiveMinimum: true
maximum: 1
description:
The weight of the agent. When used in a list of agents, the total
weights must add up to 1.
AgentOverrideRequest:
type: object
description:
Override configuration for agent, retell LLM, or conversation flow
settings for a specific call.
properties:
agent:
$ref: "#/components/schemas/AgentRequest"
description:
Override agent configuration settings. Any properties specified here
will override the base agent configuration for this call.
retell_llm:
$ref: "#/components/schemas/RetellLlmOverride"
description:
Override Retell LLM configuration settings. Only applicable when
using Retell LLM as the response engine. Supported attributes -
model, s2s_model, model_temperature, model_high_priority,
tool_call_strict_mode, knowledge_base_ids, kb_config, start_speaker,
begin_after_user_silence_ms, begin_message.
conversation_flow:
$ref: "#/components/schemas/ConversationFlowOverride"
description:
Override conversation flow configuration settings. Only applicable
when using conversation flow as the response engine. Supported
attributes - model_choice, model_temperature, tool_call_strict_mode,
knowledge_base_ids, kb_config, start_speaker,
begin_after_user_silence_ms.
AgentRequest:
type: object
properties:
response_engine:
$ref: "#/components/schemas/ResponseEngine"
description:
The Response Engine to attach to the agent. It is used to generate
responses for the agent. You need to create a Response Engine first
before attaching it to an agent.
example:
type: retell-llm
llm_id: llm_234sdertfsdsfsdf
version: 0
agent_name:
type: string
example: Jarvis
description: The name of the agent. Only used for your own reference.
nullable: true
version_description:
type: string
example: "Customer support agent for handling product inquiries"
description:
Optional description of the agent version. Used for your own
reference and documentation.
nullable: true
voice_id:
type: string
example: retell-Cimo
description:
Unique voice id used for the agent. Find list of available voices
and their preview in Dashboard.
voice_model:
type: string
enum:
- eleven_turbo_v2
- eleven_flash_v2
- eleven_turbo_v2_5
- eleven_flash_v2_5
- eleven_multilingual_v2
- eleven_v3
- sonic-3
- sonic-3-latest
- tts-1
- gpt-4o-mini-tts
- speech-02-turbo
- speech-2.8-turbo
- s1
- null
description:
Select the voice model used for the selected voice. Each provider
has a set of available voice models. Set to null to remove voice
model selection, and default ones will apply. Check out dashboard
for more details of each voice model.
nullable: true
fallback_voice_ids:
type: array
items:
type: string
example:
- cartesia-Cimo
- minimax-Cimo
description:
When TTS provider for the selected voice is experiencing outages, we
would use fallback voices listed here for the agent. Voice id and
the fallback voice ids must be from different TTS providers. The
system would go through the list in order, if the first one in the
list is also having outage, it would use the next one. Set to null
to remove voice fallback for the agent.
nullable: true
voice_temperature:
type: number
example: 1
description:
Controls how stable the voice is. Value ranging from [0,2]. Lower
value means more stable, and higher value means more variant speech
generation. Check the dashboard to see what provider supports this
feature. If unset, default value 1 will apply.
voice_speed:
type: number
minimum: 0.5
maximum: 2
example: 1
description:
Controls speed of voice. Value ranging from [0.5,2]. Lower value
means slower speech, while higher value means faster speech rate. If
unset, default value 1 will apply.
enable_dynamic_voice_speed:
type: boolean
example: true
description:
If set to true, will enable dynamic voice speed adjustment based on
the user's speech rate and conversation context. If unset, default
value false will apply.
enable_dynamic_responsiveness:
type: boolean
example: true
description:
If set to true, the agent will dynamically adjust how quickly it
responds based on the user's speech rate and past turn-taking
behavior in the call. If unset, default value false will apply.
volume:
type: number
example: 1
description:
If set, will control the volume of the agent. Value ranging from
[0,2]. Lower value means quieter agent speech, while higher value
means louder agent speech. If unset, default value 1 will apply.
voice_emotion:
type: string
nullable: true
enum:
- calm
- sympathetic
- happy
- sad
- angry
- fearful
- surprised
- null
example: calm
description: >
Controls the emotional tone of the agent's voice. Currently
supported for Cartesia and Minimax TTS providers. If unset, no
emotion will be used.
responsiveness:
type: number
minimum: 0
maximum: 1
example: 1
description:
Controls how responsive is the agent. Value ranging from [0,1].
Lower value means less responsive agent (wait more, respond slower),
while higher value means faster exchanges (respond when it can). If
unset, default value 1 will apply.
interruption_sensitivity:
type: number
minimum: 0
maximum: 1
example: 1
description:
Controls how sensitive the agent is to user interruptions. Value
ranging from [0,1]. Lower value means it will take longer / more
words for user to interrupt agent, while higher value means it's
easier for user to interrupt agent. If unset, default value 1 will
apply. When this is set to 0, agent would never be interrupted.
enable_backchannel:
type: boolean
example: true
description:
Controls whether the agent would backchannel (agent interjects the
speaker with phrases like "yeah", "uh-huh" to signify interest and
engagement). Backchannel when enabled tends to show up more in
longer user utterances. If not set, agent will not backchannel.
backchannel_frequency:
type: number
example: 0.9
description:
Only applicable when enable_backchannel is true. Controls how often
the agent would backchannel when a backchannel is possible. Value
ranging from [0,1]. Lower value means less frequent backchannel,
while higher value means more frequent backchannel. If unset,
default value 0.8 will apply.
backchannel_words:
type: array
items:
type: string
example:
- yeah
- uh-huh
description:
Only applicable when enable_backchannel is true. A list of words
that the agent would use as backchannel. If not set, default
backchannel words will apply. Check out [backchannel default
words](/agent/interaction-configuration#backchannel) for more
details. Note that certain voices do not work too well with certain
words, so it's recommended to experiment before adding any words.
nullable: true
reminder_trigger_ms:
type: number
example: 10000
description:
If set (in milliseconds), will trigger a reminder to the agent to
speak if the user has been silent for the specified duration after
some agent speech. Must be a positive number. If unset, default
value of 10000 ms (10 s) will apply.
reminder_max_count:
type: integer
example: 2
description:
If set, controls how many times agent would remind user when user is
unresponsive. Must be a non negative integer. If unset, default
value of 1 will apply (remind once). Set to 0 to disable agent from
reminding.
ambient_sound:
type: string
enum:
- coffee-shop
- convention-hall
- summer-outdoor
- mountain-outdoor
- static-noise
- call-center
- null
description: |
If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options:
- `coffee-shop`: Coffee shop ambience with people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/coffee-shop.wav)
- `convention-hall`: Convention hall ambience, with some echo and people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/convention-hall.wav)
- `summer-outdoor`: Summer outdoor ambience with cicada chirping. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/summer-outdoor.wav)
- `mountain-outdoor`: Mountain outdoor ambience with birds singing. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/mountain-outdoor.wav)
- `static-noise`: Constant static noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/static-noise.wav)
- `call-center`: Call center work noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/call-center.wav)
Set to `null` to remove ambient sound from this agent.
nullable: true
ambient_sound_volume:
type: number
example: 1
description:
If set, will control the volume of the ambient sound. Value ranging
from [0,2]. Lower value means quieter ambient sound, while higher
value means louder ambient sound. If unset, default value 1 will
apply.
language:
type: string
example: en-US
enum:
- en-US
- en-IN
- en-GB
- en-AU
- en-NZ
- de-DE
- es-ES
- es-419
- hi-IN
- fr-FR
- fr-CA
- ja-JP
- pt-PT
- pt-BR
- zh-CN
- ru-RU
- it-IT
- ko-KR
- nl-NL
- nl-BE
- pl-PL
- tr-TR
- vi-VN
- ro-RO
- bg-BG
- ca-ES
- th-TH
- da-DK
- fi-FI
- el-GR
- hu-HU
- id-ID
- no-NO
- sk-SK
- sv-SE
- lt-LT
- lv-LV
- cs-CZ
- ms-MY
- af-ZA
- ar-SA
- az-AZ
- bs-BA
- cy-GB
- fa-IR
- fil-PH
- gl-ES
- he-IL
- hr-HR
- hy-AM
- is-IS
- kk-KZ
- kn-IN
- mk-MK
- mr-IN
- ne-NP
- sl-SI
- sr-RS
- sw-KE
- ta-IN
- ur-IN
- yue-CN
- uk-UA
- multi
description:
Specifies what language (and dialect) the speech recognition will
operate in. For instance, selecting `en-GB` optimizes speech
recognition for British English. If unset, will use default value
`en-US`. Select `multi` for multilingual support.
webhook_url:
type: string
example: https://webhook-url-here
description:
The webhook for agent to listen to call events. See what events it
would get at [webhook doc](/features/webhook). If set, will binds
webhook events for this agent to the specified url, and will ignore
the account level webhook for this agent. Set to `null` to remove
webhook url from this agent.
nullable: true
webhook_events:
type: array
items:
type: string
enum:
- call_started
- call_ended
- call_analyzed
- transcript_updated
- transfer_started
- transfer_bridged
- transfer_cancelled
- transfer_ended
description:
Which webhook events this agent should receive. If not set, defaults
to call_started, call_ended, call_analyzed.
nullable: true
webhook_timeout_ms:
type: integer
example: 10000
description:
The timeout for the webhook in milliseconds. If not set, default
value of 10000 will apply.
boosted_keywords:
type: array
items:
type: string
example:
- retell
- kroger
description:
Provide a customized list of keywords to bias the transcriber model,
so that these words are more likely to get transcribed. Commonly
used for names, brands, street, etc.
nullable: true
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
example: everything
description: 'Granular setting to manage how Retell stores sensitive
data (transcripts, recordings, logs, etc.).
This replaces the deprecated `opt_out_sensitive_data_storage` field.
- `everything`: Store all data including transcripts, recordings,
and logs.
- `everything_except_pii`: Store data without PII when PII is
detected.
- `basic_attributes_only`: Store only basic attributes; no
transcripts/recordings/logs.
If not set, default value of "everything" will apply.
'
data_storage_retention_days:
type: integer
minimum: 1
maximum: 730
example: 30
nullable: true
description:
Number of days to retain call/chat data before automatic deletion.
Must be between 1 and 730 days. If not set, data is retained forever
(no automatic deletion).
opt_in_signed_url:
type: boolean
example: true
description:
Whether this agent opts in for signed URLs for public logs and
recordings. When enabled, the generated URLs will include security
signatures that restrict access and automatically expire after 24
hours.
signed_url_expiration_ms:
type: integer
example: 86400000
description:
The expiration time for the signed url in milliseconds. Only
applicable when opt_in_signed_url is true. If not set, default value
of 86400000 (24 hours) will apply.
nullable: true
pronunciation_dictionary:
type: array
items:
type: object
required:
- word
- alphabet
- phoneme
properties:
word:
type: string
example: actually
description:
The string of word / phrase to be annotated with
pronunciation.
alphabet:
type: string
enum:
- ipa
- cmu
example: ipa
description: The phonetic alphabet to be used for pronunciation.
phoneme:
type: string
example: "\u02C8\xE6kt\u0283u\u0259li"
description:
Pronunciation of the word in the format of a IPA / CMU
pronunciation.
description:
A list of words / phrases and their pronunciation to be used to
guide the audio synthesize for consistent pronunciation. Check the
dashboard to see what provider supports this feature. Set to null to
remove pronunciation dictionary from this agent.
nullable: true
normalize_for_speech:
type: boolean
example: true
description:
If set to true, will normalize the some part of text (number,
currency, date, etc) to spoken to its spoken form for more
consistent speech synthesis (sometimes the voice synthesize system
itself might read these wrong with the raw text). For example, it
will convert "Call my number 2137112342 on Jul 5th, 2024 for the
$24.12 payment" to "Call my number two one three seven one one two
three four two on july fifth, twenty twenty four for the twenty four
dollars twelve cents payment" before starting audio generation.
end_call_after_silence_ms:
type: integer
example: 600000
description:
If users stay silent for a period after agent speech, end the call.
The minimum value allowed is 10,000 ms (10 s). By default, this is
set to 600000 (10 min).
max_call_duration_ms:
type: integer
example: 3600000
description:
Maximum allowed length for the call, will force end the call if
reached. The minimum value allowed is 60,000 ms (1 min), and maximum
value allowed is 7,200,000 (2 hours). By default, this is set to
3,600,000 (1 hour).
voicemail_message:
type: string
example: Hi, please give us a callback.
description:
The message to be played when the call enters a voicemail. Note that
this feature is only available for phone calls. If you want to
hangup after hitting voicemail, set this to empty string.
voicemail_detection_timeout_ms:
type: integer
example: 30000
description:
Configures when to stop running voicemail detection, as it becomes
unlikely to hit voicemail after a couple minutes, and keep running
it will only have negative impact. The minimum value allowed is
5,000 ms (5 s), and maximum value allowed is 180,000 (3 minutes). By
default, this is set to 30,000 (30 s).
voicemail_option:
type: object
properties:
action:
$ref: "#/components/schemas/VoicemailAction"
required:
- action
description:
If this option is set, the call will try to detect voicemail in the
first 3 minutes of the call. Actions defined (hangup, or leave a
message) will be applied when the voicemail is detected. Set this to
null to disable voicemail detection.
example:
action:
type: static_text
text: Please give us a callback tomorrow at 10am.
nullable: true
ivr_option:
type: object
properties:
action:
$ref: "#/components/schemas/IvrAction"
required:
- action
description:
If this option is set, the call will try to detect IVR in the first
3 minutes of the call. Actions defined will be applied when the IVR
is detected. Set this to null to disable IVR detection.
example:
action:
type: hangup
nullable: true
post_call_analysis_data:
type: array
items:
$ref: "#/components/schemas/PostCallAnalysisData"
description:
Post call analysis data to extract from the call. This data will
augment the pre-defined variables extracted in the call analysis.
This will be available after the call ends.
nullable: true
post_call_analysis_model:
$ref: "#/components/schemas/NullableLLMModel"
example: gpt-4.1-mini
description:
The model to use for post call analysis. Default to gpt-4.1-mini.
analysis_successful_prompt:
type: string
maxLength: 2000
example:
The agent finished the task and the call was complete without being
cutoff.
description:
Prompt to determine whether the post call or chat analysis should
mark the interaction as successful. Set to null to use the default
prompt.
nullable: true
analysis_summary_prompt:
type: string
maxLength: 2000
example: Summarize the outcome of the conversation in two sentences.
description:
Prompt to guide how the post call or chat analysis summary should be
generated. When unset, the default system prompt is used. Set to
null to use the default prompt.
nullable: true
analysis_user_sentiment_prompt:
type: string
maxLength: 2000
example:
Evaluate the user's sentiment based on their tone and satisfaction
level.
description:
Prompt to guide how the post call or chat analysis should evaluate
user sentiment. When unset, the default system prompt is used. Set
to null to use the default prompt.
nullable: true
begin_message_delay_ms:
type: integer
example: 1000
description:
If set, will delay the first message by the specified amount of
milliseconds, so that it gives user more time to prepare to take the
call. Valid range is [0, 5000]. If not set or set to 0, agent will
speak immediately. Only applicable when agent speaks first.
ring_duration_ms:
type: integer
minimum: 5000
maximum: 300000
example: 30000
description:
If set, the phone ringing will last for the specified amount of
milliseconds. This applies for both outbound call ringtime, and call
transfer ringtime. Default to 30000 (30 s). Valid range is [5000,
300000].
stt_mode:
type: string
enum:
- fast
- accurate
- custom
example: fast
description:
If set, determines whether speech to text should focus on latency or
accuracy. Default to fast mode. When set to custom,
custom_stt_config must be provided.
custom_stt_config:
type: object
description:
Custom STT configuration. Only used when stt_mode is set to custom.
properties:
provider:
type: string
enum:
- azure
- deepgram
description: The STT provider to use.
endpointing_ms:
type: integer
description:
Endpointing timeout in milliseconds. Minimum is 100 for azure,
10 for deepgram.
required:
- provider
- endpointing_ms
nullable: true
vocab_specialization:
type: string
enum:
- general
- medical
example: general
description:
If set, determines the vocabulary set to use for transcription. This
setting only applies for English agents, for non English agent, this
setting is a no-op. Default to general.
allow_user_dtmf:
type: boolean
example: true
description:
If set to true, DTMF input will be accepted and processed. If false,
any DTMF input will be ignored. Default to true.
user_dtmf_options:
type: object
properties:
digit_limit:
type: number
description:
The maximum number of digits allowed in the user's DTMF
(Dual-Tone Multi-Frequency) input per turn. Once this limit is
reached, the input is considered complete and a response will be
generated immediately.
nullable: true
minimum: 1
maximum: 50
termination_key:
type: string
nullable: true
description:
A single key that signals the end of DTMF input. Acceptable
values include any digit (0-9), the pound/hash symbol (#), or
the asterisk (*).
example: "#"
timeout_ms:
type: integer
description:
The time (in milliseconds) to wait for user DTMF input before
timing out. The timer resets with each digit received.
minimum: 1000
maximum: 15000
nullable: true
denoising_mode:
type: string
enum:
- no-denoise
- noise-cancellation
- noise-and-background-speech-cancellation
example: noise-cancellation
description:
If set, determines what denoising mode to use. Use "no-denoise" to
bypass all audio denoising. Default to noise-cancellation.
pii_config:
$ref: "#/components/schemas/PIIConfig"
description:
Configuration for PII scrubbing from transcripts and recordings.
guardrail_config:
$ref: "#/components/schemas/GuardrailConfig"
description:
Configuration for guardrail checks to detect and prevent prohibited
topics in agent output and user input.
handbook_config:
$ref: "#/components/schemas/VoiceHandbookConfig"
description:
Toggle behavior presets on/off to influence agent response style and
behaviors.
timezone:
type: string
description:
IANA timezone for the agent (e.g. America/New_York). Defaults to
America/Los_Angeles if not set.
example: America/New_York
nullable: true
is_public:
type: boolean
example: false
description:
Whether the agent is public. When set to true, the agent is
available for public agent preview link.
nullable: true
AgentResponse:
allOf:
- type: object
required:
- agent_id
- version
properties:
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Unique id of agent.
version:
type: integer
example: 0
description: Version of the agent.
is_published:
type: boolean
example: false
description: Whether the agent is published.
- $ref: "#/components/schemas/AgentRequest"
required:
- response_engine
- voice_id
- 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.
AgentSwapNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- agent_id
- post_call_analysis_setting
- edge
properties:
type:
type: string
enum:
- agent_swap
description: Type of the node
agent_id:
type: string
description: The ID of the agent to swap to
agent_version:
type: number
description:
The version of the agent to swap to. If not specified, will use
the latest version
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.
edge:
$ref: "#/components/schemas/TransferFailedEdge"
description: Edge to transition to if agent swap fails
speak_during_execution:
type: boolean
description: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
What to say when swapping agents, only used when speak during
execution
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:
type: number
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
AgentSwapWebhookSetting:
type: string
enum:
- both_agents
- only_destination_agent
- only_source_agent
AnalysisData:
oneOf:
- $ref: "#/components/schemas/StringAnalysisData"
- $ref: "#/components/schemas/EnumAnalysisData"
- $ref: "#/components/schemas/BooleanAnalysisData"
- $ref: "#/components/schemas/NumberAnalysisData"
PostCallAnalysisData:
oneOf:
- $ref: "#/components/schemas/AnalysisData"
- $ref: "#/components/schemas/CallPresetAnalysisData"
description:
Post-call analysis item (custom data or voice preset). Use for voice
agent post_call_analysis_data; validates only call presets
(call_summary, call_successful, user_sentiment).
PostChatAnalysisData:
oneOf:
- $ref: "#/components/schemas/AnalysisData"
- $ref: "#/components/schemas/ChatPresetAnalysisData"
description:
Post-chat analysis item (custom data or chat preset). Use for chat agent
post_chat_analysis_data; validates only chat presets (chat_summary,
chat_successful, user_sentiment).
AverageMetric:
type: object
required:
- time_averages
- overall_average
properties:
time_averages:
type: array
items:
type: number
overall_average:
type: number
numerator:
type: number
denominator:
type: number
BatchCallResponse:
type: object
required:
- batch_call_id
- name
- from_number
- scheduled_timestamp
- total_task_count
properties:
batch_call_id:
type: string
example: batch_call_dbcc4412483ebfc348abb
description: Unique id of the batch call.
name:
type: string
example: First batch call
from_number:
type: string
example: "+14157774444"
scheduled_timestamp:
type: number
example: 1735718400
total_task_count:
type: number
description: Number of tasks within the batch call
call_time_window:
$ref: "#/components/schemas/CallTimeWindow"
description:
Canonicalized minutes-based time windows. Present only if specified
when the batch call was created or updated. See CallTimeWindow for
format details ([startMin, endMin) in local minutes; no
cross-midnight).
BatchCallTask:
type: object
required:
- to_number
properties:
to_number:
type: string
minLength: 1
example: "+12137774445"
description:
The The number you want to call, in E.164 format. If using a number
purchased from Retell, only US numbers are supported as destination.
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
override_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
For this particular call, override the agent used with this agent
id. This does not bind the agent to this number, this is for one
time override.
override_agent_version:
type: integer
example: 1
description:
For this particular call, override the agent version used with this
version. This does not bind the agent to this number, this is for
one time override.
agent_override:
$ref: "#/components/schemas/AgentOverrideRequest"
description:
For this particular call, override agent configuration with these
settings. This allows you to customize agent behavior for individual
calls without modifying the base agent.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string that
injects into your Response Engine prompt and tool description. Only
applicable for Response Engine.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put anything
here like your internal customer id associated with the call. Not
used for processing. You can later get this field from the call
object.
custom_sip_headers:
type: object
additionalProperties:
type: string
example:
X-Custom-Header: Custom Value
description: Add optional custom SIP headers to the call.
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
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.
BranchNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- else_edge
properties:
type:
type: string
enum:
- branch
description: Type of the node
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
else_edge:
$ref: "#/components/schemas/ElseEdge"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
BreakdownMetric:
type: object
required:
- overall_breakdown
- time_breakdown
properties:
overall_breakdown:
type: array
items:
$ref: "#/components/schemas/Breakdown"
time_breakdown:
type: array
items:
type: array
items:
$ref: "#/components/schemas/Breakdown"
Breakdown:
type: object
required:
- metric_name
- metric_value
properties:
metric_name:
type: string
metric_value:
type: number
BridgeTransferNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
properties:
type:
type: string
enum:
- bridge_transfer
description:
Type of the node - initiates a warm transfer by bridging the
call
speak_during_execution:
type: boolean
description: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
Describes what to say to user when bridging the transfer. Only
applicable when speak_during_execution is true.
BridgeTransferTool:
type: object
properties:
type:
type: string
enum:
- bridge_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 bridges the original caller to
the transfer target 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 bridging 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
CallAnalysis:
type: object
properties:
call_summary:
type: string
example:
The agent called the user to ask question about his purchase
inquiry. The agent asked several questions regarding his preference
and asked if user would like to book an appointment. The user
happily agreed and scheduled an appointment next Monday 10am.
description: A high level summary of the call.
in_voicemail:
type: boolean
example: false
description: Whether the call is entered voicemail.
user_sentiment:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
example: Positive
description: Sentiment of the user in the call.
call_successful:
type: boolean
example: true
description:
Whether the agent seems to have a successful call with the user,
where the agent finishes the task, and the call was complete without
being cutoff.
custom_analysis_data:
type: object
description:
Custom analysis data that was extracted based on the schema defined
in agent post call analysis data. Can be empty if nothing is
specified.
CallLatency:
type: object
properties:
p50:
type: number
description: 50 percentile of latency, measured in milliseconds.
example: 800
p90:
type: number
description: 90 percentile of latency, measured in milliseconds.
example: 1200
p95:
type: number
description: 95 percentile of latency, measured in milliseconds.
example: 1500
p99:
type: number
description: 99 percentile of latency, measured in milliseconds.
example: 2500
max:
type: number
description: Maximum latency in the call, measured in milliseconds.
example: 2700
min:
type: number
description: Minimum latency in the call, measured in milliseconds.
example: 500
num:
type: number
description:
Number of data points (number of times latency is tracked).
example: 10
values:
type: array
items:
type: number
description:
All the latency data points in the call, measured in milliseconds.
CallQA:
type: object
required:
- call_qa_id
- call_id
- cohort_id
- cohort_version
- db_version
- deprecated
- score
- passed
- wer
- call_start_time_ms
- created_at
- updated_at
- calibrated
properties:
call_qa_id:
type: string
call_id:
type: string
cohort_id:
type: string
cohort_version:
type: number
db_version:
type: number
deprecated:
type: boolean
score:
type: number
passed:
type: boolean
wer:
$ref: "#/components/schemas/WER"
interruptions:
$ref: "#/components/schemas/InterruptionAnalysis"
user_sentiments:
$ref: "#/components/schemas/SentimentAnalysis"
agent_sentiments:
$ref: "#/components/schemas/SentimentAnalysis"
agent_naturalness_issues:
$ref: "#/components/schemas/AgentNaturalnessAnalysis"
mistranscribed_important_entities:
$ref: "#/components/schemas/MistranscribedImportantEntitiesAnalysis"
rag_analysis:
$ref: "#/components/schemas/RAGAnalysis"
tool_call_invocation_analysis:
$ref: "#/components/schemas/ToolCallInvocationAnalysis"
tool_call_analysis:
$ref: "#/components/schemas/ToolCallAccuracyAnalysis"
node_transition_analysis:
$ref: "#/components/schemas/NodeTransitionAnalysis"
llm_hallucination_analysis:
$ref: "#/components/schemas/HallucinationAnalysis"
transfer_call_analysis:
type: object
properties:
latency:
type: array
items:
type: number
successful:
type: array
items:
type: boolean
failure_reason:
type: string
failed_metrics:
type: array
items:
$ref: "#/components/schemas/MetricResult"
passed_metrics:
type: array
items:
$ref: "#/components/schemas/MetricResult"
recommendations:
type: array
items:
type: string
notes:
type: string
call_start_time_ms:
type: number
created_at:
type: number
updated_at:
type: number
calibrated:
type: boolean
CallTimeWindow:
type: object
description:
Allowed calling windows in a specific timezone. Each window is a
half-open interval [startMin, endMin) in minutes since 00:00 local time.
Cross-midnight windows are NOT allowed (must satisfy startMin < endMin).
`endMin = 1440` (24:00) is valid.
properties:
windows:
type: array
minItems: 1
items:
$ref: "#/components/schemas/TimeWindow"
description:
List of TimeWindow (start/end in minutes since local midnight).
timezone:
type: string
description:
IANA timezone (e.g. America/Los_Angeles). Defaults to
America/Los_Angeles if omitted.
day:
type: array
items:
$ref: "#/components/schemas/DayOfWeek"
description:
Optional list of days to which the windows apply. If omitted or
empty, windows apply to every day.
required:
- windows
CancelTransferNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
properties:
type:
type: string
enum:
- cancel_transfer
description:
Type of the node - cancels the warm transfer and ends the
transfer agent call
speak_during_execution:
type: boolean
description: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
Describes what to say to user when cancelling the transfer. Only
applicable when speak_during_execution is true.
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
ChCallQA:
type: object
required:
- call_qa_id
- call_id
- cohort_id
- call_start_time_ms
- db_version
- deprecated
- score
- passed
- calibrated
properties:
call_qa_id:
type: string
call_id:
type: string
cohort_id:
type: string
call_start_time_ms:
type: number
db_version:
type: number
deprecated:
type: boolean
score:
type: number
passed:
type: boolean
word_count:
type: number
number_deletions:
type: number
number_insertions:
type: number
number_substitutions:
type: number
interruption_count:
type: number
llm_inference_count:
type: number
llm_hallucination_count:
type: number
user_positive_sentiment_count:
type: number
user_neutral_sentiment_count:
type: number
user_negative_sentiment_count:
type: number
agent_positive_sentiment_count:
type: number
agent_neutral_sentiment_count:
type: number
agent_negative_sentiment_count:
type: number
agent_natural_utterance_count:
type: number
rag_success_count:
type: number
rag_total_count:
type: number
transfer_call_success_count:
type: number
transfer_call_total_count:
type: number
transfer_call_avg_latency:
type: number
tool_call_average_latency:
type: number
tool_call_success_count:
type: number
tool_call_total_count:
type: number
tool_call_accurate_utterance_count:
type: number
tool_call_total_utterance_count:
type: number
transition_success_count:
type: number
transition_total_count:
type: number
agent_total_utterance_count:
type: number
user_total_utterance_count:
type: number
calibrated:
type: boolean
ChatAgentRequest:
type: object
properties:
response_engine:
$ref: "#/components/schemas/ResponseEngine"
description:
The Response Engine to attach to the agent. It is used to generate
responses for the agent. You need to create a Response Engine first
before attaching it to an agent.
example:
type: retell-llm
llm_id: llm_234sdertfsdsfsdf
version: 0
agent_name:
type: string
example: Jarvis
description:
The name of the chat agent. Only used for your own reference.
nullable: true
auto_close_message:
type: string
example: Thank you for chatting. The conversation has ended.
description: Message to display when the chat is automatically closed.
nullable: true
end_chat_after_silence_ms:
type: integer
example: 3600000
description:
If users stay silent for a period after agent speech, end the chat.
The minimum value allowed is 120,000 ms (2 minutes). The maximum
value allowed is 259,200,000 ms (72 hours). By default, this is set
to 3,600,000 (1 hour).
nullable: true
language:
type: string
example: en-US
enum:
- en-US
- en-IN
- en-GB
- en-AU
- en-NZ
- de-DE
- es-ES
- es-419
- hi-IN
- fr-FR
- fr-CA
- ja-JP
- pt-PT
- pt-BR
- zh-CN
- ru-RU
- it-IT
- ko-KR
- nl-NL
- nl-BE
- pl-PL
- tr-TR
- th-TH
- vi-VN
- ro-RO
- bg-BG
- ca-ES
- da-DK
- fi-FI
- el-GR
- hu-HU
- id-ID
- no-NO
- sk-SK
- sv-SE
- lt-LT
- lv-LV
- cs-CZ
- multi
description:
Specifies what language (and dialect) the chat will operate in. For
instance, selecting `en-GB` optimizes for British English. If unset,
will use default value `en-US`. Select `multi` for multilingual
support, currently this supports Spanish and English.
webhook_url:
type: string
example: https://webhook-url-here
description:
The webhook for agent to listen to chat events. See what events it
would get at [webhook doc](/features/webhook). If set, will binds
webhook events for this agent to the specified url, and will ignore
the account level webhook for this agent. Set to `null` to remove
webhook url from this agent.
nullable: true
webhook_events:
type: array
items:
type: string
enum:
- chat_started
- chat_ended
- chat_analyzed
description:
Which webhook events this agent should receive. If not set, defaults
to chat_started, chat_ended, chat_analyzed.
nullable: true
webhook_timeout_ms:
type: integer
example: 10000
description:
The timeout for the webhook in milliseconds. If not set, default
value of 10000 will apply.
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
example: everything
description:
Controls what data is stored for this agent. "everything" stores all
data including transcripts and recordings. "everything_except_pii"
stores data but excludes PII when possible based on PII
configuration. "basic_attributes_only" stores only basic metadata.
If not set, defaults to "everything".
nullable: true
data_storage_retention_days:
type: integer
minimum: 1
maximum: 730
example: 30
nullable: true
description:
Number of days to retain call/chat data before automatic deletion.
Must be between 1 and 730 days. If not set, data is retained forever
(no automatic deletion).
opt_in_signed_url:
type: boolean
example: true
description:
Whether this agent opts in to signed url for public log. If not set,
default value of false will apply.
signed_url_expiration_ms:
type: integer
example: 86400000
description:
The expiration time for the signed url in milliseconds. Only
applicable when opt_in_signed_url is true. If not set, default value
of 86400000 (24 hours) will apply.
nullable: true
post_chat_analysis_data:
type: array
items:
$ref: "#/components/schemas/PostChatAnalysisData"
description:
Post chat analysis data to extract from the chat. This data will
augment the pre-defined variables extracted in the chat analysis.
This will be available after the chat ends.
nullable: true
post_chat_analysis_model:
$ref: "#/components/schemas/NullableLLMModel"
example: gpt-4.1-mini
description:
The model to use for post chat analysis. Default to gpt-4.1-mini.
analysis_successful_prompt:
type: string
example:
The agent finished the task and the call was complete without being
cutoff.
description:
The prompt to use for post call analysis to evaluate whether the
call is successful. Set to null to use the default prompt.
nullable: true
analysis_summary_prompt:
type: string
example: Summarize the call in a few sentences.
description:
The prompt to use for post call analysis to summarize the call. Set
to null to use the default prompt.
nullable: true
analysis_user_sentiment_prompt:
type: string
maxLength: 2000
example:
Evaluate the user's sentiment based on their tone and satisfaction
level.
description:
Prompt to guide how the post chat analysis should evaluate user
sentiment. When unset, the default system prompt is used. Set to
null to use the default prompt.
nullable: true
pii_config:
$ref: "#/components/schemas/PIIConfig"
description:
Configuration for PII scrubbing from transcripts and recordings.
guardrail_config:
$ref: "#/components/schemas/GuardrailConfig"
description:
Configuration for guardrail checks to detect and prevent prohibited
topics in agent output and user input.
handbook_config:
$ref: "#/components/schemas/ChatHandbookConfig"
description:
Toggle behavior presets on/off to influence agent response style and
behaviors. Voice-only presets are not available for chat agents.
timezone:
type: string
description:
IANA timezone for the agent (e.g. America/New_York). Defaults to
America/Los_Angeles if not set.
example: America/New_York
nullable: true
is_public:
type: boolean
example: false
description:
Whether the agent is public. When set to true, the agent is
available for public agent preview link.
nullable: true
ChatAgentResponse:
allOf:
- type: object
required:
- agent_id
properties:
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Unique id of chat agent.
version:
type: integer
example: 0
description: The version of the chat agent.
is_published:
type: boolean
example: false
description: Whether the chat agent is published.
- $ref: "#/components/schemas/ChatAgentRequest"
required:
- response_engine
- 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.
ChatAnalysis:
type: object
properties:
chat_summary:
type: string
example:
The agent messages user to ask question about his purchase inquiry.
The agent asked several questions regarding his preference and asked
if user would like to book an appointment. The user happily agreed
and scheduled an appointment next Monday 10am.
description: A high level summary of the chat.
user_sentiment:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
example: Positive
description: Sentiment of the user in the chat.
chat_successful:
type: boolean
example: true
description:
Whether the agent seems to have a successful chat with the user,
where the agent finishes the task, and the call was complete without
being cutoff.
custom_analysis_data:
type: object
description:
Custom analysis data that was extracted based on the schema defined
in chat agent post chat analysis data. Can be empty if nothing is
specified.
ChatResponse:
type: object
required:
- chat_id
- agent_id
- chat_status
properties:
chat_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the chat.
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Corresponding chat agent id of this chat.
version:
type: integer
example: 1
description: The version of the agent
nullable: true
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string that
injects into your Response Engine prompt and tool description. Only
applicable for Response Engine.
collected_dynamic_variables:
type: object
additionalProperties: {}
example:
last_node_name: Test node
description:
Dynamic variables collected from the chat. Only available after the
chat ends.
chat_status:
type: string
enum:
- ongoing
- ended
- error
example: ongoing
description: |
Status of chat.
- `ongoing`: Chat session is ongoing, chat agent can receive new message and generate response.
- `ended`: Chat session has ended, and no longer can generate new response.
- `error`: Chat encountered error.
chat_type:
type: string
enum:
- api_chat
- sms_chat
example: api_chat
description: Type of the chat
custom_attributes:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
description: Custom attributes for the chat
start_timestamp:
type: integer
example: 1703302407333
description:
Begin timestamp (milliseconds since epoch) of the chat. Available
after chat starts.
end_timestamp:
type: integer
example: 1703302428855
description:
End timestamp (milliseconds since epoch) of the chat. Available
after chat ends.
nullable: true
transcript:
type: string
example: |
Agent: hi how are you doing?
User: Doing pretty well. How are you?
Agent: That's great to hear! I'm doing well too, thanks! What's up?
User: I don't have anything in particular.
Agent: Got it, just checking in!
User: Alright. See you.
Agent: have a nice day
description: Transcription of the chat.
message_with_tool_calls:
type: array
items:
$ref: "#/components/schemas/MessageOrToolCall"
description:
Transcript of the chat weaved with tool call invocation and results.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put anything
here like your internal customer id associated with the chat. Not
used for processing. You can later get this field from the chat
object.
chat_cost:
type: object
properties:
product_costs:
type: array
description:
List of products with their unit prices and costs in cents
items:
$ref: "#/components/schemas/ProductCost"
combined_cost:
type: number
description: Combined cost of all individual costs in cents
example: 70
chat_analysis:
description:
Post chat analysis that includes information such as sentiment,
status, summary, and custom defined data to extract. Available after
chat ends. Subscribe to `chat_analyzed` webhook event type to
receive it once ready.
$ref: "#/components/schemas/ChatAnalysis"
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
CohortAgent:
type: object
required:
- cohort_id
- agent_id
properties:
cohort_id:
type: string
agent_id:
type: string
minLength: 1
agent_versions:
type: array
items:
type: number
CohortAggregatedResult:
type: object
required:
- calls_analysed
- timepoints
- group_by
- avg_score
- call_resolution_rate
- top_questions
- top_recommendations
- latency
- llm_hallucination_analysis
- rag_analysis
- user_sentiment
- agent_sentiment
- transfer_success_rate
- transfer_wait_time
- wer
- avg_interruption
- tool_call_accuracy
- transition_accuracy
- natural_tonality_rate
- custom_tool_call_latency
- custom_tool_call_success_rate
properties:
calls_analysed:
type: array
items:
type: number
timepoints:
type: array
items:
type: number
group_by:
type: string
enum:
- hour
- day
- week
- month
avg_score:
$ref: "#/components/schemas/AverageMetric"
call_resolution_rate:
$ref: "#/components/schemas/AverageMetric"
top_questions:
type: array
items:
type: object
required:
- question_cluster_id
- text
- count
- resolved
properties:
question_cluster_id:
type: string
description: ID of the question cluster
text:
type: string
description: Text of the question
resolved:
type: number
description: Number of resolved occurrences
count:
type: number
description: Total count of occurrences
top_recommendations:
type: array
items:
type: object
required:
- text
- count
properties:
text:
type: string
count:
type: number
latency:
$ref: "#/components/schemas/AverageMetric"
llm_hallucination_analysis:
$ref: "#/components/schemas/AverageMetric"
rag_analysis:
$ref: "#/components/schemas/AverageMetric"
user_sentiment:
$ref: "#/components/schemas/BreakdownMetric"
agent_sentiment:
$ref: "#/components/schemas/BreakdownMetric"
transfer_success_rate:
$ref: "#/components/schemas/AverageMetric"
transfer_wait_time:
$ref: "#/components/schemas/AverageMetric"
wer:
$ref: "#/components/schemas/AverageMetric"
avg_interruption:
$ref: "#/components/schemas/AverageMetric"
tool_call_accuracy:
$ref: "#/components/schemas/AverageMetric"
transition_accuracy:
$ref: "#/components/schemas/AverageMetric"
natural_tonality_rate:
$ref: "#/components/schemas/AverageMetric"
custom_tool_call_latency:
$ref: "#/components/schemas/AverageMetric"
custom_tool_call_success_rate:
$ref: "#/components/schemas/AverageMetric"
CohortFilter:
type: object
description: Call filter criteria to create QA.
properties:
agent:
type: array
minItems: 1
maxItems: 100
items:
$ref: "#/components/schemas/AgentFilter"
description: Filter by agent(s), which are connected by "OR".
start_timestamp:
oneOf:
- allOf:
- $ref: "#/components/schemas/NumberFilter"
- properties:
op:
enum:
- ge
- $ref: "#/components/schemas/RangeFilter"
description: Start timestamp filter (epoch ms). Required.
disconnection_reason:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description:
Filter calls by disconnection reason. If not specified, all
disconnection reasons are included.
properties:
value:
items:
$ref: "#/components/schemas/DisconnectionReason"
duration_ms:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter calls by duration in milliseconds.
custom_analysis_data:
type: array
items:
$ref: "#/components/schemas/CustomFieldFilter"
description: Filter calls by custom analysis data fields.
agents:
type: array
minItems: 1
maxItems: 200
items:
$ref: "#/components/schemas/AgentFilter"
deprecated: true
description:
"Deprecated: use 'agent' instead. Either 'agent' or 'agents' must be
provided."
date_range:
$ref: "#/components/schemas/DateRange"
deprecated: true
description: "Deprecated: use 'start_timestamp' instead."
call_duration_filter:
type: object
required:
- value
- op
properties:
value:
type: number
op:
type: string
enum:
- gt
- gte
- lt
- lte
- eq
- ne
deprecated: true
description: "Deprecated: use 'duration_ms' instead."
post_call_analysis:
type: object
description:
"Deprecated: use 'custom_analysis_data' instead. Custom analysis
data filter criteria for filtering calls based on custom analysis
data."
deprecated: true
disconnection_reasons:
type: array
items:
$ref: "#/components/schemas/DisconnectionReason"
deprecated: true
description: "Deprecated: use 'disconnection_reason' instead."
Cohort:
type: object
required:
- cohort_id
- name
- cohort_filter
- sampling_percentage
- scoring_criteria
- successful_criteria
properties:
cohort_id:
type: string
name:
type: string
maxLength: 100
cohort_filter:
$ref: "#/components/schemas/CohortFilter"
sampling_percentage:
type: number
minimum: 0.01
maximum: 100
sampling_weekly_max:
type: number
minimum: 0
scoring_criteria:
$ref: "#/components/schemas/ScoringCriteria"
successful_criteria:
type: object
required:
- value
- op
properties:
type:
type: string
enum:
- number
description: Type of the filter
value:
type: number
minimum: 0
maximum: 100
op:
type: string
enum:
- gt
- gte
- ge
ComponentNode:
allOf:
- $ref: "#/components/schemas/NodeBaseCommon"
- type: object
required:
- type
- component_id
- component_type
- else_edge
properties:
type:
type: string
enum:
- component
description: Type of the node
component_id:
type: string
description: The reference ID of the component
component_type:
type: string
enum:
- local
- shared
description: "Type of component:
- local: stored in conversation flow's components array
- shared: stored in stand-alone conversation-flow-component
table
"
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
description: Array of edges for conditional transitions
else_edge:
$ref: "#/components/schemas/ElseEdge"
description: Default edge when no other conditions are met
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
ConversationFlowComponentResponse:
allOf:
- $ref: "#/components/schemas/CreateConversationFlowComponentRequest"
- type: object
required:
- conversation_flow_component_id
- user_modified_timestamp
properties:
conversation_flow_component_id:
type: string
description: Unique identifier for the component
user_modified_timestamp:
type: integer
format: int64
description: Timestamp of last user modification
linked_conversation_flow_ids:
type: array
items:
type: string
description:
IDs of conversation flows linked to this shared component
Asset:
type: object
properties:
asset_id:
type: string
description: Unique identifier for the asset.
example: asset_abc123def456
file_name:
type: string
description: Original file name of the uploaded asset.
example: screenshot.png
content_type:
type: string
description: MIME type of the asset.
example: image/png
file_size:
type: number
description: File size in bytes.
example: 204800
url:
type: string
description: CDN URL to access the asset.
example: https://cdn.example.com/asset/org_123/asset_abc123def456/screenshot.png
created_timestamp:
type: number
description: Unix timestamp of when the asset was created.
example: 1710000000000
Note:
type: object
required:
- id
- content
- display_position
- size
properties:
id:
type: string
description: Unique identifier for the note.
example: note_abc123
content:
type: string
description:
Text content of the note, can contain refs to images in the format
"<image:asset_id>"
example: Remember to handle edge cases here.
display_position:
type: object
properties:
x:
type: number
example: 300
y:
type: number
example: 150
description: Position of the note on the canvas.
size:
type: object
properties:
width:
type: number
example: 200
height:
type: number
example: 100
description: Dimensions of the note on the canvas.
ConversationFlowComponent:
type: object
properties:
name:
type: string
description: Name of the component
example: Customer Information Collector
tools:
type: array
items:
$ref: "#/components/schemas/NodeTool"
description: Tools available within the component
example:
- type: custom
name: get_customer_info
description: Get customer information from database
tool_id: tool_001
url: https://api.example.com/customer
method: GET
nullable: true
mcps:
type: array
items:
$ref: "#/components/schemas/MCP"
description:
A list of MCP server configurations to use for this component
nullable: true
nodes:
type: array
items:
$ref: "#/components/schemas/ConversationFlowNode"
description: Nodes that make up the component
example:
- id: collect_info
type: conversation
instruction:
type: prompt
text: Ask the customer for their name and contact information.
start_node_id:
type: string
description: ID of the starting node
example: collect_info
nullable: true
begin_tag_display_position:
type: object
properties:
x:
type: number
example: 100
y:
type: number
example: 200
description: Display position for the begin tag in the frontend
nullable: true
notes:
type: array
items:
$ref: "#/components/schemas/Note"
description: Visual annotations displayed on the flow canvas.
nullable: true
ConversationFlowNode:
oneOf:
- $ref: "#/components/schemas/ConversationNode"
- $ref: "#/components/schemas/SubagentNode"
- $ref: "#/components/schemas/EndNode"
- $ref: "#/components/schemas/FunctionNode"
- $ref: "#/components/schemas/CodeNode"
- $ref: "#/components/schemas/TransferCallNode"
- $ref: "#/components/schemas/PressDigitNode"
- $ref: "#/components/schemas/BranchNode"
- $ref: "#/components/schemas/SmsNode"
- $ref: "#/components/schemas/ExtractDynamicVariablesNode"
- $ref: "#/components/schemas/AgentSwapNode"
- $ref: "#/components/schemas/MCPNode"
- $ref: "#/components/schemas/ComponentNode"
- $ref: "#/components/schemas/BridgeTransferNode"
- $ref: "#/components/schemas/CancelTransferNode"
AgentOverrideConfig:
type: object
properties:
interruption_sensitivity:
type: number
minimum: 0
maximum: 1
nullable: true
responsiveness:
type: number
minimum: 0
maximum: 1
nullable: true
voice_speed:
type: number
minimum: 0.5
maximum: 2
nullable: true
ConversationFlowOverride:
type: object
description:
Override properties for conversation flow configuration in agent
override requests.
properties:
model_choice:
$ref: "#/components/schemas/ModelChoice"
description: The model choice for the conversation flow.
model_temperature:
type: number
minimum: 0
maximum: 1
example: 0.7
description:
Controls the randomness of the model's responses. Lower values make
responses more deterministic.
nullable: true
tool_call_strict_mode:
type: boolean
example: true
description:
Whether to use strict mode for tool calls. Only applicable when
using certain supported models.
nullable: true
knowledge_base_ids:
type: array
items:
type: string
example:
- kb_001
- kb_002
description:
Knowledge base IDs for RAG (Retrieval-Augmented Generation).
nullable: true
kb_config:
type: object
$ref: "#/components/schemas/KBConfig"
description: Knowledge base configuration for RAG retrieval.
start_speaker:
type: string
enum:
- user
- agent
example: agent
description: Who starts the conversation - user or agent.
begin_after_user_silence_ms:
type: integer
example: 2000
description:
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.
nullable: true
ConversationFlowResponse:
allOf:
- $ref: "#/components/schemas/ConversationFlow"
- type: object
required:
- conversation_flow_id
- version
properties:
conversation_flow_id:
type: string
description: Unique identifier for the conversation flow
version:
type: integer
description: Version number of the conversation flow
ConversationFlow:
allOf:
- $ref: "#/components/schemas/ConversationFlowOverride"
- type: object
properties:
global_prompt:
type: string
example: You are a helpful customer service agent.
description:
Global prompt used in every node of the conversation flow.
nullable: true
tools:
type: array
items:
$ref: "#/components/schemas/NodeTool"
description: Tools available in the conversation flow.
example:
- type: custom
name: get_customer_info
description: Get customer information from database
tool_id: tool_001
url: https://api.example.com/customer
method: GET
nullable: true
components:
type: array
items:
$ref: "#/components/schemas/CreateConversationFlowComponentRequest"
description:
Local components embedded within the conversation flow.
nullable: true
start_node_id:
type: string
example: start
description: ID of the start node in the conversation flow.
nullable: true
default_dynamic_variables:
type: object
additionalProperties:
type: string
example:
company_name: Retell Inc
support_hours: 9 AM - 5 PM
description:
Default dynamic variables that can be referenced throughout the
conversation flow.
nullable: true
begin_tag_display_position:
type: object
properties:
x:
type: number
example: 100
y:
type: number
example: 200
description: Display position for the begin tag in the frontend.
nullable: true
notes:
type: array
items:
$ref: "#/components/schemas/Note"
description: Visual annotations displayed on the flow canvas.
nullable: true
mcps:
type: array
items:
$ref: "#/components/schemas/MCP"
description:
A list of MCP server configurations to use for this conversation
flow.
nullable: true
is_transfer_llm:
type: boolean
example: false
description:
Whether this conversation flow is used for transfer LLM.
nullable: true
nodes:
type: array
items:
$ref: "#/components/schemas/ConversationFlowNode"
description: Array of nodes in the conversation flow.
example:
- id: start
type: conversation
instruction:
type: prompt
text: Greet the customer and ask how you can help them.
edges:
- id: edge_1
transition_condition:
type: prompt
prompt: Customer wants to book appointment
destination_node_id: book_appointment
ConversationNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- $ref: "#/components/schemas/AgentOverrideConfig"
- type: object
required:
- type
- instruction
properties:
type:
type: string
enum:
- conversation
description: Type of the node
instruction:
$ref: "#/components/schemas/NodeInstruction"
skip_response_edge:
$ref: "#/components/schemas/SkipResponseEdge"
always_edge:
$ref: "#/components/schemas/AlwaysEdge"
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
finetune_conversation_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneConversationExample"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
knowledge_base_ids:
type: array
items:
type: string
example:
- kb_001
- kb_002
description:
Knowledge base IDs for RAG (Retrieval-Augmented Generation).
nullable: true
SubagentNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- $ref: "#/components/schemas/AgentOverrideConfig"
- type: object
required:
- type
- instruction
properties:
type:
type: string
enum:
- subagent
description: Type of the node
instruction:
$ref: "#/components/schemas/NodeInstructionPrompt"
skip_response_edge:
$ref: "#/components/schemas/SkipResponseEdge"
always_edge:
$ref: "#/components/schemas/AlwaysEdge"
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
finetune_conversation_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneConversationExample"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
knowledge_base_ids:
type: array
items:
type: string
description:
Knowledge base IDs for RAG (Retrieval-Augmented Generation).
nullable: true
tool_ids:
type: array
items:
type: string
description:
The tool ids of the tools defined in main conversation flow or
component that can be used in this subagent node.
nullable: true
tools:
type: array
items:
$ref: "#/components/schemas/Tool"
description:
The tools owned by this subagent node. This includes other tool
types like transfer_call, agent_swap, etc.
nullable: true
CpsConfig:
type: object
description:
Calls Per Second (CPS) configuration for different telephony providers
properties:
twilio:
type: integer
nullable: true
description: CPS limit for Twilio provider (1-5)
example: 3
telnyx:
type: integer
nullable: true
description: CPS limit for Telnyx provider (1-16)
example: 10
custom:
type: integer
nullable: true
description: CPS limit for custom provider 1 to concurrency / 20
example: 2
CreateConversationFlowComponentRequest:
allOf:
- $ref: "#/components/schemas/ConversationFlowComponent"
- type: object
required:
- name
- nodes
CreateConversationFlowRequest:
allOf:
- $ref: "#/components/schemas/ConversationFlow"
- type: object
required:
- start_speaker
- model_choice
- nodes
CreateOrganizationRequest:
oneOf:
- $ref: "#/components/schemas/CreateOrganizationRequestNew"
- $ref: "#/components/schemas/CreateOrganizationRequestOld"
CreateOrganizationRequestNew:
type: object
required:
- org_name
properties:
org_name:
type: string
description: Name of the organization
example: My Organization
minLength: 1
maxLength: 100
CreateOrganizationRequestOld:
type: object
required:
- orgName
properties:
orgName:
type: string
description: Name of the organization
example: My Organization
minLength: 1
maxLength: 100
CustomMetricCriteria:
type: object
required:
- name
- description
- score_weight
properties:
name:
type: string
description: Name of the custom metric
description:
type: string
description: Description of the custom metric
score_weight:
type: number
minimum: 1
maximum: 100
description: Weight for scoring (1-100)
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".
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: 5000
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".
required:
- type
- name
- code
DTMFUtterance:
type: object
required:
- role
- digit
properties:
role:
type: string
enum:
- dtmf
description: Digit pressed by the user from their phone keypad.
digit:
type: string
description:
The digit pressed by the user. Will be a single digit string like
"1", "2", "3", "*", "#" etc.
example: "1"
StringFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- string
op:
type: string
enum:
- eq
- ne
- sw
- ew
- co
description:
"eq: equal, ne: not equal, sw: starts with, ew: ends with, co:
contains"
value:
type: string
NumberFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- number
op:
type: string
enum:
- eq
- ne
- gt
- ge
- lt
- le
description:
"eq: equal, ne: not equal, gt: greater than, ge: greater than or
equal, lt: less than, le: less than or equal"
value:
type: number
BooleanFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- boolean
op:
type: string
enum:
- eq
value:
type: boolean
RangeFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- range
op:
type: string
enum:
- bt
description: "bt: between"
value:
type: array
minItems: 2
maxItems: 2
items:
type: number
description: "[lower_bound, upper_bound]"
EnumFilter:
type: object
required:
- type
- op
- value
properties:
type:
type: string
enum:
- enum
op:
type: string
enum:
- in
description: "in: value is one of the listed values"
value:
type: array
items:
type: string
PresentFilter:
type: object
required:
- type
- op
properties:
type:
type: string
enum:
- present
op:
type: string
enum:
- pr
- np
description: "pr: present (has value), np: not present"
ValueFilter:
oneOf:
- $ref: "#/components/schemas/StringFilter"
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/BooleanFilter"
- $ref: "#/components/schemas/RangeFilter"
- $ref: "#/components/schemas/EnumFilter"
- $ref: "#/components/schemas/PresentFilter"
CustomFieldFilter:
description: A filter on a custom field, identified by key.
allOf:
- $ref: "#/components/schemas/ValueFilter"
- type: object
required:
- key
properties:
key:
type: string
description: The field name to filter on.
AgentFilter:
type: object
required:
- agent_id
properties:
agent_id:
type: string
minLength: 1
description: The agent ID to filter on.
version:
type: array
items:
type: number
description:
Specific versions to filter on. If not provided, all versions are
included.
ToolCallFilter:
type: object
required:
- name
properties:
name:
type: string
description: The tool call name to filter on.
latency_ms:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by tool call latency in milliseconds.
success:
$ref: "#/components/schemas/BooleanFilter"
description: Filter by tool call success status.
CallFilter:
type: object
description:
"Filter criteria for calls. All conditions are implicitly connected with
AND."
properties:
agent:
type: array
items:
$ref: "#/components/schemas/AgentFilter"
description: Filter by agent(s). Agent filters are connected by OR.
call_id:
$ref: "#/components/schemas/StringFilter"
description: Filter by call ID.
batch_call_id:
$ref: "#/components/schemas/StringFilter"
description: Filter by batch call ID.
call_status:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by call status.
properties:
value:
items:
enum:
- not_connected
- ongoing
- ended
- error
in_voicemail:
$ref: "#/components/schemas/BooleanFilter"
description: Filter by whether the call is in voicemail.
disconnection_reason:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by disconnection reason.
properties:
value:
items:
$ref: "#/components/schemas/DisconnectionReason"
from_number:
$ref: "#/components/schemas/StringFilter"
description: Filter by from number.
to_number:
$ref: "#/components/schemas/StringFilter"
description: Filter by to number.
call_type:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by call type.
properties:
value:
items:
enum:
- web_call
- phone_call
direction:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by call direction.
properties:
value:
items:
enum:
- inbound
- outbound
user_sentiment:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by user sentiment.
properties:
value:
items:
enum:
- Negative
- Positive
- Neutral
- Unknown
data_storage_setting:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by data storage setting.
properties:
value:
items:
enum:
- everything
- everything_except_pii
- basic_attributes_only
call_successful:
$ref: "#/components/schemas/BooleanFilter"
description: Filter by whether the call was successful.
start_timestamp:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by call start timestamp (epoch ms).
end_timestamp:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by call end timestamp (epoch ms).
duration_ms:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by call duration in milliseconds.
combined_cost:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by combined cost of the call.
e2e_latency_p50:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Filter by end-to-end latency p50.
tool_calls:
type: array
items:
$ref: "#/components/schemas/ToolCallFilter"
description:
Filter by tool call criteria. Tool call filters are connected by
AND.
custom_analysis_data:
type: array
items:
$ref: "#/components/schemas/CustomFieldFilter"
description: Filter by custom analysis data fields.
custom_attributes:
type: array
items:
$ref: "#/components/schemas/CustomFieldFilter"
description: Filter by custom attributes fields.
metadata:
type: array
items:
$ref: "#/components/schemas/CustomFieldFilter"
description: Filter by metadata fields.
dynamic_variables:
type: array
items:
allOf:
- $ref: "#/components/schemas/StringFilter"
- type: object
required:
- key
properties:
key:
type: string
description: The dynamic variable name to filter on.
description: Filter by dynamic variables.
DateRange:
type: object
required:
- start_time_ms
properties:
start_time_ms:
type: number
end_time_ms:
type: number
DayOfWeek:
type: string
enum:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
- Sunday
description: Day of week. Matches server-side DayOfWeek enum.
DisconnectionReason:
type: string
enum:
- user_hangup
- agent_hangup
- call_transfer
- voicemail_reached
- ivr_reached
- inactivity
- max_duration_reached
- concurrency_limit_reached
- no_valid_payment
- scam_detected
- dial_busy
- dial_failed
- dial_no_answer
- invalid_destination
- telephony_provider_permission_denied
- telephony_provider_unavailable
- sip_routing_error
- marked_as_spam
- user_declined
- error_llm_websocket_open
- error_llm_websocket_lost_connection
- error_llm_websocket_runtime
- error_llm_websocket_corrupt_payload
- error_no_audio_received
- error_asr
- error_retell
- error_unknown
- error_user_not_joined
- registered_call_timeout
- transfer_bridged
- transfer_cancelled
Duration:
type: object
required:
- start_sec
- end_sec
properties:
start_sec:
type: number
description: Start time in seconds
end_sec:
type: number
description: End time in seconds
ElseEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Else
description: Must be "Else" for else edge
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
EndNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
properties:
type:
type: string
enum:
- end
description: Type of the node
speak_during_execution:
type: boolean
description: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
What to say when ending the call, only used when speak during
execution
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.
EquationCondition:
type: object
required:
- type
- equations
- operator
properties:
type:
type: string
enum:
- equation
equations:
type: array
maxItems: 50
items:
$ref: "#/components/schemas/Equation"
operator:
type: string
enum:
- "||"
- "&&"
Equation:
type: object
required:
- left
- operator
properties:
left:
type: string
description: Left side of the equation
operator:
type: string
enum:
- ==
- "!="
- ">"
- ">="
- <
- <=
- contains
- not_contains
- exists
- not_exist
right:
type: string
description:
Right side of the equation. The right side of the equation not
required when "exists" or "not_exist" are selected.
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
ExtractDynamicVariablesNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- variables
properties:
type:
type: string
enum:
- extract_dynamic_variables
description: Type of the node
variables:
type: array
items:
$ref: "#/components/schemas/AnalysisData"
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
else_edge:
$ref: "#/components/schemas/ElseEdge"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
FinetuneExampleUtterance:
oneOf:
- type: object
required:
- role
- content
properties:
role:
type: string
enum:
- agent
- user
content:
type: string
- type: object
required:
- role
- tool_call_id
- name
- arguments
properties:
role:
type: string
enum:
- tool_call_invocation
tool_call_id:
type: string
name:
type: string
arguments:
type: string
- type: object
required:
- role
- tool_call_id
- content
properties:
role:
type: string
enum:
- tool_call_result
tool_call_id:
type: string
content:
type: string
FunctionNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- tool_id
- tool_type
- wait_for_result
properties:
type:
type: string
enum:
- function
description: Type of the node
tool_id:
type: string
description: Tool ID for function nodes
tool_type:
type: string
enum:
- local
- shared
description: Tool type for function nodes
speak_during_execution:
type: boolean
description: Whether to speak during tool execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
wait_for_result:
type: boolean
description: Whether to wait for tool result
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
else_edge:
$ref: "#/components/schemas/ElseEdge"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
CodeNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- code
- wait_for_result
properties:
type:
type: string
enum:
- code
description: Type of the node
code:
type: string
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: Whether to speak during code execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
wait_for_result:
type: boolean
description: Whether to wait for code execution result
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
else_edge:
$ref: "#/components/schemas/ElseEdge"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
GlobalNodeFinetuneTransitionExample:
type: object
required:
- transcript
properties:
transcript:
type: array
items:
$ref: "#/components/schemas/FinetuneExampleUtterance"
description: Find tune the transition condition to this global node
GlobalNodeSetting:
type: object
required:
- condition
properties:
condition:
type: string
description: Condition for global node activation, cannot be empty
go_back_conditions:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
description:
The conditions for global node go back. There would be no
destination_node_id for these edges.
cool_down:
type: number
minimum: 1
description:
The same global node won't be triggered again within the next N node
transitions.
positive_finetune_examples:
type: array
items:
$ref: "#/components/schemas/GlobalNodeFinetuneTransitionExample"
description: Transition to this node
negative_finetune_examples:
type: array
items:
$ref: "#/components/schemas/GlobalNodeFinetuneTransitionExample"
description: Don't transition to this node
HallucinationAnalysis:
type: object
required:
- details
- hallucination_utterance_count
- total_utterance_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/UtteranceHallucination"
hallucination_utterance_count:
type: number
total_utterance_count:
type: number
Hallucination:
type: object
required:
- type
- reason
properties:
type:
type: string
enum:
- Fabrication
- Contradiction
- Confusion
reason:
type: string
low_severity:
type: boolean
description:
true = minor hallucination, false/undefined = major hallucination
(defaults to major for backward compatibility)
InterruptionAnalysis:
type: object
required:
- details
- interruption_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/Duration"
interruption_count:
type: number
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
KnowledgeBaseAddSourcesRequest:
type: object
properties:
knowledge_base_texts:
type: array
items:
type: object
required:
- title
- text
properties:
title:
type: string
description: Title of the text.
text:
type: string
description: Text to add to the knowledge base.
description: Texts to add to the knowledge base.
knowledge_base_files:
type: array
items:
type: string
format: binary
description:
Files to add to the knowledge base. Limit to 25 files, where each
file is limited to 50MB.
knowledge_base_urls:
type: array
items:
type: string
example:
- https://www.example.com
- https://www.retellai.com
description:
URLs to be scraped and added to the knowledge base. Must be valid
urls.
KnowledgeBaseRequest:
type: object
required:
- knowledge_base_name
properties:
knowledge_base_name:
type: string
example: Sample KB
description:
Name of the knowledge base. Must be less than 40 characters.
knowledge_base_texts:
type: array
items:
type: object
required:
- title
- text
properties:
title:
type: string
description: Title of the text.
text:
type: string
description: Text to add to the knowledge base.
description: Texts to add to the knowledge base.
knowledge_base_files:
type: array
items:
type: string
format: binary
description:
Files to add to the knowledge base. Limit to 25 files, where each
file is limited to 50MB.
knowledge_base_urls:
type: array
items:
type: string
example:
- https://www.example.com
- https://www.retellai.com
description:
URLs to be scraped and added to the knowledge base. Must be valid
urls.
enable_auto_refresh:
type: boolean
example: true
description:
Whether to enable auto refresh for the knowledge base urls. If set
to true, will retrieve the data from the specified url every 12
hours.
max_chunk_size:
type: integer
minimum: 600
maximum: 6000
example: 2000
description:
Maximum number of characters per chunk when splitting knowledge
base. Default is 2000. content. Immutable after creation.
min_chunk_size:
type: integer
minimum: 200
maximum: 2000
example: 400
description:
Minimum number of characters per chunk. Chunks smaller than this
will be merged with adjacent chunks. Must be less than
max_chunk_size. Immutable after creation. Default is 400.
KnowledgeBaseResponse:
type: object
required:
- knowledge_base_id
- knowledge_base_name
- status
properties:
knowledge_base_id:
type: string
example: knowledge_base_a456426614174000
description: Unique id of the knowledge base.
knowledge_base_name:
type: string
example: Sample KB
description:
Name of the knowledge base. Must be less than 40 characters.
status:
type: string
enum:
- in_progress
- complete
- error
- refreshing_in_progress
example: in_progress
description:
Status of the knowledge base. When it's created and being processed,
it's "in_progress". When the processing is done, it's "complete".
When there's an error in processing, it's "error". When it is during
kb updating, it's "refreshing_in_progress".
max_chunk_size:
type: integer
example: 2000
description:
Maximum number of characters per chunk when splitting knowledge base
content.
min_chunk_size:
type: integer
example: 400
description:
Minimum number of characters per chunk. Chunks smaller than this are
merged with adjacent chunks.
knowledge_base_sources:
type: array
items:
oneOf:
- $ref: "#/components/schemas/KnowledgeBaseSourceDocument"
- $ref: "#/components/schemas/KnowledgeBaseSourceText"
- $ref: "#/components/schemas/KnowledgeBaseSourceUrl"
description:
Sources of the knowledge base. Will be populated after the
processing is done (when status is "complete").
enable_auto_refresh:
type: boolean
example: true
description:
Whether to enable auto refresh for the knowledge base urls. If set
to true, will retrieve the data from the specified url every 12
hours.
last_refreshed_timestamp:
type: integer
example: 1703413636133
description:
Last refreshed timestamp (milliseconds since epoch). Only applicable
when enable_auto_refresh is true.
KnowledgeBaseSourceDocument:
type: object
required:
- type
- source_id
- filename
- file_url
- file_size
properties:
type:
type: string
enum:
- document
description: Type of the knowledge base source.
source_id:
type: string
description: Unique id of the knowledge base source.
filename:
type: string
description: Filename of the document.
file_url:
type: string
description: URL of the document stored.
KnowledgeBaseSourceText:
type: object
required:
- type
- source_id
- title
- content_url
properties:
type:
type: string
enum:
- text
description: Type of the knowledge base source.
source_id:
type: string
description: Unique id of the knowledge base source.
title:
type: string
description: Title of the text.
content_url:
type: string
description: URL of the text content stored.
KnowledgeBaseSourceUrl:
type: object
required:
- type
- source_id
- url
properties:
type:
type: string
enum:
- url
description: Type of the knowledge base source.
source_id:
type: string
description: Unique id of the knowledge base source.
url:
type: string
description: URL used to be scraped and added to the knowledge base.
LLMModel:
type: string
enum:
- gpt-4.1
- gpt-4.1-mini
- gpt-4.1-nano
- 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
- claude-4.5-sonnet
- claude-4.6-sonnet
- claude-4.5-haiku
- gemini-2.5-flash
- gemini-2.5-flash-lite
- gemini-3.0-flash
description: Available LLM models for agents.
MCPNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- mcp_id
- mcp_tool_name
- wait_for_result
properties:
type:
type: string
enum:
- mcp
description: Type of the node
mcp_id:
type: string
description: Unique ID of the MCP server
mcp_tool_name:
type: string
description: Name of the MCP tool to call
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
else_edge:
$ref: "#/components/schemas/ElseEdge"
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: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
What to say when calling the function, only used when speak
during execution
wait_for_result:
type: boolean
description:
If true, will wait for result before transitioning to next node
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
MCPToolDefinition:
type: object
properties:
name:
type: string
description: Name of the MCP tool.
example: search_files
description:
type: string
description: Description of what the MCP tool does.
example: Search for files in the filesystem
inputSchema:
type: object
description: JSON schema defining the input parameters for the tool.
additionalProperties: true
example:
type: object
properties:
query:
type: string
description: Search query
required:
- query
required:
- name
- description
- inputSchema
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".
required:
- type
- name
- description
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
MessageOrToolCall:
oneOf:
- $ref: "#/components/schemas/Message"
- $ref: "#/components/schemas/ToolCallInvocationMessage"
- $ref: "#/components/schemas/ToolCallResultMessage"
- $ref: "#/components/schemas/NodeTransitionMessage"
- $ref: "#/components/schemas/StateTransitionMessage"
Message:
type: object
required:
- message_id
- role
- content
- created_timestamp
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- agent
- user
description: Documents whether this message is sent by agent or user.
example: agent
content:
type: string
description: Content of the message
example: hi how are you doing?
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
MetricResult:
type: object
required:
- metric_criteria
properties:
metric_criteria:
oneOf:
- $ref: "#/components/schemas/PerformanceMetricCriteria"
- $ref: "#/components/schemas/CustomMetricCriteria"
description:
Can be either a PerformanceMetricCriteria or CustomMetricCriteria
object.
value:
description:
The calculated value of the metric. Omittable for custom metric
criteria.
oneOf:
- type: number
- type: boolean
- type: string
vote:
type: boolean
description: An optional vote based on the metric result.
MistranscribedImportantEntitiesAnalysis:
type: object
required:
- details
- mie_utterance_count
- total_utterance_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/UtteranceMistranscribedImportantEntities"
mie_utterance_count:
type: number
total_utterance_count:
type: number
ModelChoiceCascading:
type: object
required:
- type
- model
properties:
type:
type: string
enum:
- cascading
description: Type of model choice
model:
$ref: "#/components/schemas/LLMModel"
description: The LLM model to use
high_priority:
type: boolean
description:
Whether to use high priority pool with more dedicated resource,
default false
ModelChoice:
oneOf:
- $ref: "#/components/schemas/ModelChoiceCascading"
NaturalnessIssue:
type: string
enum:
- Too Loud
- Too Quiet
- Too Fast
- Too Slow
- Unclear Pronunciation
- Unnatural Pauses
- Robotic Tone
- Other
NodeBase:
allOf:
- $ref: "#/components/schemas/NodeBaseCommon"
- type: object
properties:
model_choice:
$ref: "#/components/schemas/ModelChoice"
NodeBaseCommon:
type: object
required:
- id
properties:
id:
type: string
description: Unique identifier for the node
name:
type: string
description: Optional name for display purposes
global_node_setting:
$ref: "#/components/schemas/GlobalNodeSetting"
display_position:
type: object
properties:
x:
type: number
y:
type: number
description: Position for frontend display
NodeEdge:
type: object
required:
- id
- transition_condition
properties:
id:
type: string
description: Unique identifier for the edge
transition_condition:
oneOf:
- $ref: "#/components/schemas/PromptCondition"
- $ref: "#/components/schemas/EquationCondition"
destination_node_id:
type: string
description: ID of the destination node
NodeFinetuneConversationExample:
type: object
required:
- id
- transcript
properties:
id:
type: string
description: Unique identifier for the example
transcript:
type: array
items:
$ref: "#/components/schemas/FinetuneExampleUtterance"
description:
The example transcript to finetune how the conversation should be.
NodeFinetuneTransitionExample:
type: object
required:
- id
- transcript
properties:
id:
type: string
description: Unique identifier for the example
transcript:
type: array
items:
$ref: "#/components/schemas/FinetuneExampleUtterance"
description:
The example transcript to finetune how the node should transition.
destination_node_id:
type: string
description: Optional destination node ID
NodeInstructionPrompt:
type: object
required:
- type
- text
properties:
type:
type: string
enum:
- prompt
description: Type of instruction
text:
type: string
description: The prompt text for the instruction
NodeInstructionStaticText:
type: object
required:
- type
- text
properties:
type:
type: string
enum:
- static_text
description: Type of instruction
text:
type: string
description: The static text for the instruction
NodeInstruction:
oneOf:
- $ref: "#/components/schemas/NodeInstructionPrompt"
- $ref: "#/components/schemas/NodeInstructionStaticText"
NodeTool:
allOf:
- oneOf:
- $ref: "#/components/schemas/CustomTool"
- $ref: "#/components/schemas/CheckAvailabilityCalTool"
- $ref: "#/components/schemas/BookAppointmentCalTool"
- type: object
required:
- tool_id
properties:
tool_id:
type: string
description: Unique identifier for the tool
NodeTransitionAnalysis:
type: object
required:
- details
- accuracy
- correct_count
- total_count
properties:
details:
type: array
items:
type: object
properties:
time_sec:
type: number
accurate:
type: boolean
correct_node_id:
type: number
accuracy:
type: number
correct_count:
type: number
total_count:
type: number
NodeTransitionMessage:
type: object
required:
- message_id
- role
- created_timestamp
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- node_transition
description: This is a node transition.
former_node_id:
type: string
description: Former node id
former_node_name:
type: string
description: Former node name
new_node_id:
type: string
description: New node id
new_node_name:
type: string
description: New node name
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
NodeTransitionUtterance:
type: object
required:
- role
- former_node_id
- former_node_name
- new_node_id
- new_node_name
properties:
role:
type: string
enum:
- node_transition
description: This is result of a node transition
former_node_id:
type: string
description: Former node id
former_node_name:
type: string
description: Former node name
new_node_id:
type: string
description: New node id
new_node_name:
type: string
description: New node name
NullableLLMModel:
type: string
enum:
- gpt-4.1
- gpt-4.1-mini
- gpt-4.1-nano
- 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
- claude-4.5-sonnet
- claude-4.6-sonnet
- claude-4.5-haiku
- gemini-2.5-flash
- gemini-2.5-flash-lite
- gemini-3.0-flash
- null
nullable: true
description: Available LLM models for agents.
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.
PresetAnalysisData:
type: object
required:
- type
- name
- description
description:
System preset for post-call or post-chat analysis (summary, success,
sentiment). Presets can be included in post_call_analysis_data or
post_chat_analysis_data to override prompts or mark fields optional.
properties:
type:
type: string
enum:
- system-presets
description: Identifies this item as a system preset.
name:
type: string
enum:
- call_summary
- call_successful
- chat_summary
- chat_successful
- user_sentiment
description:
Preset identifier. Use call_summary/call_successful for voice;
chat_summary/chat_successful for chat; user_sentiment for both.
example: call_summary
description:
type: string
minLength: 1
description: Prompt or description for this preset.
required:
type: boolean
description:
If false, this field is optional in the analysis. If true or unset,
the field is required.
conditional_prompt:
type: string
description:
Optional instruction to help decide whether this field needs to be
populated. If not set, the field is always included.
CallPresetAnalysisData:
type: object
required:
- type
- name
description:
System preset for post-call analysis (voice agents). Use in
post_call_analysis_data to override prompts or mark fields optional.
properties:
type:
type: string
enum:
- system-presets
description: Identifies this item as a system preset.
name:
type: string
enum:
- call_summary
- call_successful
- user_sentiment
description: Preset identifier for voice agent analysis.
example: call_summary
description:
type: string
minLength: 1
description: Prompt or description for this preset.
required:
type: boolean
description:
If false, this field is optional in the analysis. If true or unset,
the field is required.
conditional_prompt:
type: string
description:
Optional instruction to help decide whether this field needs to be
populated. If not set, the field is always included.
ChatPresetAnalysisData:
type: object
required:
- type
- name
description:
System preset for post-chat analysis (chat agents). Use in
post_chat_analysis_data to override prompts or mark fields optional.
properties:
type:
type: string
enum:
- system-presets
description: Identifies this item as a system preset.
name:
type: string
enum:
- chat_summary
- chat_successful
- user_sentiment
description: Preset identifier for chat agent analysis.
example: chat_summary
description:
type: string
minLength: 1
description: Prompt or description for this preset.
required:
type: boolean
description:
If false, this field is optional in the analysis. If true or unset,
the field is required.
conditional_prompt:
type: string
description:
Optional instruction to help decide whether this field needs to be
populated. If not set, the field is always included.
Organization:
type: object
properties:
org_name:
type: string
description: Name of the organization
example: My Organization
minLength: 1
maxLength: 100
orgName:
type: string
description: Name of the organization
example: My Organization
minLength: 1
maxLength: 100
outage_mode_enabled:
type: boolean
description: Whether outage mode is enabled
webhook_urls:
type: array
items:
type: object
properties:
url:
type: string
timeout_ms:
type: integer
webhook_key:
type: string
description: API key for webhook authentication
concurrency:
type: integer
description: Maximum concurrent calls allowed
concurrency_burst_enabled:
type: boolean
description:
Whether burst concurrency mode is enabled. When enabled, allows the
org to exceed their normal concurrency limit (up to 3x or +300,
whichever is lower) with a $0.10/min surcharge on burst calls.
max_token_length:
type: integer
description: Maximum token length
max_call_duration_ms:
type: integer
description: Maximum call duration in milliseconds
custom_voice_ids:
type: array
items:
type: string
twilio_subaccount_sid:
type: string
kyc_passed:
type: boolean
description: Whether KYC verification has been passed
created_timestamp:
type: integer
description: Unix timestamp of creation
skip_audit:
type: boolean
review_provided:
type: boolean
cps_config:
type: object
properties:
twilio:
type: number
telnyx:
type: number
custom:
type: number
enterprise_id:
type: string
feature_bucket:
type: object
additionalProperties: true
use_stable_server:
type: boolean
OrganizationResponse:
allOf:
- $ref: "#/components/schemas/Organization"
- type: object
properties:
org_id:
type: string
description: Unique identifier of the organization
PIIConfig:
type: object
required:
- mode
- categories
properties:
mode:
type: string
enum:
- post_call
default: post_call
description:
The processing mode for PII scrubbing. Currently only post-call is
supported.
categories:
type: array
items:
type: string
enum:
- person_name
- address
- email
- phone_number
- ssn
- passport
- driver_license
- credit_card
- bank_account
- password
- pin
- medical_id
- date_of_birth
- customer_account_number
uniqueItems: true
default: []
description:
List of PII categories to scrub from transcripts and recordings.
GuardrailConfig:
type: object
properties:
output_topics:
type: array
items:
type: string
enum:
- harassment
- self_harm
- sexual_exploitation
- violence
- defense_and_national_security
- illicit_and_harmful_activity
- gambling
- regulated_professional_advice
- child_safety_and_exploitation
uniqueItems: true
description:
Selected prohibited agent topic categories to check. When agent
messages contain these topics, they will be replaced with a
placeholder message.
nullable: true
input_topics:
type: array
items:
type: string
enum:
- platform_integrity_jailbreaking
uniqueItems: true
description:
Selected prohibited user topic categories to check. When user
messages contain these topics, the agent will respond with a
placeholder message instead of processing the request.
nullable: true
VoiceHandbookConfig:
type: object
description: Behavior presets for voice agents. All presets are available.
properties:
default_personality:
type: boolean
description: Professional call center rep baseline.
natural_filler_words:
type: boolean
description: Sprinkle natural speech fillers like "um", "you know" for a more human, conversational tone.
high_empathy:
type: boolean
description: Warm acknowledgment of caller concerns.
echo_verification:
type: boolean
description: Repeat back and confirm important details (voice only).
nato_phonetic_alphabet:
type: boolean
description: Spell using NATO phonetic alphabet style (voice only).
speech_normalization:
type: boolean
description: Convert numbers/dates/currency to spoken forms (voice only).
smart_matching:
type: boolean
description:
Treat near-match similar words as same entity to reduce impact of
transcription error (voice only).
ai_disclosure:
type: boolean
description: When asked, acknowledge being a virtual assistant.
scope_boundaries:
type: boolean
description: Stay within prompt/context scope, don't invent details.
ChatHandbookConfig:
type: object
description: Behavior presets for chat agents. Voice-only presets are excluded.
properties:
default_personality:
type: boolean
description: Professional call center rep baseline.
high_empathy:
type: boolean
description: Warm acknowledgment of caller concerns.
ai_disclosure:
type: boolean
description: When asked, acknowledge being a virtual assistant.
scope_boundaries:
type: boolean
description: Stay within prompt/context scope, don't invent details.
PerformanceMetricCriteria:
type: object
required:
- metric_type
- op
- value
- score_weight
properties:
metric_type:
type: object
description: Performance metric type
op:
type: string
enum:
- gt
- gte
- ge
- lt
- lte
- le
- eq
- ne
description: Comparison operator for filtering
value:
type: number
score_weight:
type: number
minimum: 1
maximum: 100
description: Weight for scoring (1-100)
PhoneNumberResponse:
type: object
required:
- phone_number
- phone_number_type
- last_modification_timestamp
properties:
phone_number:
type: string
example: "+14157774444"
description:
E.164 format of the number (+country code, then number with no
space, no special characters), used as the unique identifier for
phone number APIs.
phone_number_type:
type: string
enum:
- retell-twilio
- retell-telnyx
- custom
example: retell-twilio
description: Type of the phone number.
phone_number_pretty:
type: string
example: +1 (415) 777-4444
description: Pretty printed phone number, provided for your reference.
inbound_agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when receiving inbound calls. If null,
this number would not accept inbound call. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when conducting outbound calls. If null,
this number would not be able to initiate outbound call without
agent id override. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agent_version:
type: integer
example: 1
description:
Version of the inbound agent to bind to the number. If not provided,
will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_version:
type: integer
example: 1
description:
Version of the outbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
allowed_inbound_country_list:
type: array
items:
type: string
example: ["US", "CA", "GB"]
description:
List of ISO 3166-1 alpha-2 country codes from which inbound calls
are allowed. If not set or empty, calls from all countries are
allowed.
nullable: true
allowed_outbound_country_list:
type: array
items:
type: string
example: ["US", "CA"]
description:
List of ISO 3166-1 alpha-2 country codes to which outbound calls are
allowed. If not set or empty, calls to all countries are allowed.
nullable: true
area_code:
type: integer
example: 415
description:
Area code of the number to obtain. Format is a 3 digit integer.
Currently only supports US area code.
inbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound agents to bind to the number with weights. If set and
non-empty, one agent will be picked randomly for each inbound call,
with probability proportional to the weight. Total weights must add
up to 1. If not set or empty, fallback to inbound_agent_id.
nullable: true
outbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound agents to bind to the number with weights. If set and
non-empty, one agent will be picked randomly for each outbound call,
with probability proportional to the weight. Total weights must add
up to 1. If not set or empty, fallback to outbound_agent_id.
nullable: true
inbound_sms_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound SMS agents to bind to the number with weights. If set and
non-empty, one agent will be picked randomly for each inbound SMS,
with probability proportional to the weight. Total weights must add
up to 1. If not set or empty, fallback to inbound_sms_agent_id.
nullable: true
outbound_sms_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound SMS agents to bind to the number with weights. If set and
non-empty, one agent will be picked randomly for each outbound SMS,
with probability proportional to the weight. Total weights must add
up to 1. If not set or empty, fallback to outbound_sms_agent_id.
nullable: true
nickname:
type: string
example: Frontdesk Number
description: Nickname of the number. This is for your reference only.
nullable: true
inbound_webhook_url:
type: string
example: https://example.com/inbound-webhook
description:
If set, will send a webhook for inbound calls, where you can to
override agent id, set dynamic variables and other fields specific
to that call.
nullable: true
inbound_sms_webhook_url:
type: string
example: https://example.com/inbound-sms-webhook
description:
If set, will send a webhook for inbound SMS, where you can override
agent id, set dynamic variables and other fields specific to that
chat.
nullable: true
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.
sip_outbound_trunk_config:
type: object
nullable: true
properties:
termination_uri:
type: string
example: someuri.pstn.twilio.com
nullable: true
description:
The termination URI for the SIP trunk for the phone number.
auth_username:
type: string
example: username
nullable: true
description:
The username used for authenticating the SIP trunk for the phone
number.
transport:
type: string
example: TCP
nullable: true
description:
Outbound transport protocol for the SIP trunk for the phone
number. Valid values are "TLS", "TCP" and "UDP". Default is
"TCP".
fallback_number:
type: string
example: "+14155551234"
description:
Enterprise only. Phone number to transfer inbound calls to when
organization is in outage mode. Can be either a Retell phone number
or an external number. Cannot be the same as this phone number, and
cannot be a number that already has its own fallback configured
(prevents nested forwarding).
nullable: true
PostCallAnalysisSetting:
type: string
enum:
- both_agents
- only_destination_agent
PressDigitNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- instruction
properties:
type:
type: string
enum:
- press_digit
description: Type of the node
instruction:
$ref: "#/components/schemas/NodeInstructionPrompt"
delay_ms:
type: integer
description: Delay in milliseconds before pressing the digit
edges:
type: array
items:
$ref: "#/components/schemas/NodeEdge"
finetune_transition_examples:
type: array
items:
$ref: "#/components/schemas/NodeFinetuneTransitionExample"
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
ProductCost:
type: object
required:
- product
- cost
properties:
product:
type: string
description: Product name that has a cost associated with it.
example: elevenlabs_tts
unit_price:
type: number
description: Unit price of the product in cents per second.
example: 1
cost:
type: number
description:
Cost for the product in cents for the duration of the call.
example: 60
is_transfer_leg_cost:
type: boolean
description: True if this cost item is for a transfer segment.
PromptCondition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
description: Prompt condition text
QaViewFilter:
type: object
description: "Filter criteria for QA views."
properties:
agent:
type: array
maxItems: 100
items:
$ref: "#/components/schemas/AgentFilter"
description: Filter by agent(s).
start_timestamp:
oneOf:
- $ref: "#/components/schemas/NumberFilter"
- $ref: "#/components/schemas/RangeFilter"
description: Start timestamp filter (epoch ms).
score:
$ref: "#/components/schemas/NumberFilter"
description: Filter by QA score.
disconnection_reason:
allOf:
- $ref: "#/components/schemas/EnumFilter"
- description: Filter by disconnection reason(s).
properties:
value:
items:
$ref: "#/components/schemas/DisconnectionReason"
passed:
oneOf:
- type: boolean
- $ref: "#/components/schemas/BooleanFilter"
calibrated:
oneOf:
- type: boolean
- $ref: "#/components/schemas/BooleanFilter"
agents:
type: array
items:
$ref: "#/components/schemas/AgentFilter"
deprecated: true
description: "Deprecated: use 'agent' instead."
date_range:
$ref: "#/components/schemas/DateRange"
deprecated: true
description: "Deprecated: use 'start_timestamp' instead."
score_range:
type: object
required:
- value
- op
properties:
type:
type: string
enum:
- number
value:
type: number
op:
type: string
enum:
- gt
- gte
- ge
deprecated: true
description: "Deprecated: use 'score' instead."
disconnection_reasons:
type: array
items:
$ref: "#/components/schemas/DisconnectionReason"
deprecated: true
description: "Deprecated: use 'disconnection_reason' instead."
RAGAccuracy:
type: object
required:
- response_id
- false_positive
- false_negative
- true_positive
- true_negative
properties:
response_id:
type: number
false_positive:
type: number
false_negative:
type: number
true_positive:
type: number
true_negative:
type: number
RAGAnalysis:
type: object
required:
- details
- rag_accurate_count
- rag_total_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/RAGAccuracy"
rag_accurate_count:
type: number
rag_total_count:
type: number
ResponseEngineConversationFlow:
type: object
required:
- type
- conversation_flow_id
properties:
type:
type: string
enum:
- conversation-flow
description: type of the Response Engine.
conversation_flow_id:
type: string
description: ID of the Conversation Flow Response Engine.
version:
type: number
example: 0
description: Version of the Conversation Flow Response Engine.
nullable: true
ResponseEngineCustomLm:
type: object
required:
- type
- llm_websocket_url
properties:
type:
type: string
enum:
- custom-llm
description: type of the Response Engine.
llm_websocket_url:
type: string
description: LLM websocket url of the custom LLM.
ResponseEngineRetellLm:
type: object
required:
- type
- llm_id
properties:
type:
type: string
enum:
- retell-llm
description: type of the Response Engine.
llm_id:
type: string
description: id of the Retell LLM Response Engine.
version:
type: number
example: 0
description: Version of the Retell LLM Response Engine.
nullable: true
ResponseEngine:
oneOf:
- $ref: "#/components/schemas/ResponseEngineRetellLm"
- $ref: "#/components/schemas/ResponseEngineCustomLm"
- $ref: "#/components/schemas/ResponseEngineConversationFlow"
RetellResponseEngine:
oneOf:
- $ref: "#/components/schemas/ResponseEngineRetellLm"
- $ref: "#/components/schemas/ResponseEngineConversationFlow"
description: Response engine for test cases. Custom LLM is not supported.
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.
RetellLlmOverride:
type: object
description:
Override properties for Retell LLM configuration in agent override
requests.
properties:
model:
$ref: "#/components/schemas/NullableLLMModel"
example: gpt-4.1
description:
Select the underlying text LLM. If not set, would default to
gpt-4.1.
s2s_model:
type: string
enum:
- gpt-realtime-1.5
- gpt-realtime
- gpt-realtime-mini
- null
example: gpt-realtime-1.5
description:
Select the underlying speech to speech model. Can only set this or
model, not both.
nullable: true
model_temperature:
type: number
example: 0
description:
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.
model_high_priority:
type: boolean
example: true
description:
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.
nullable: true
tool_call_strict_mode:
type: boolean
example: true
description:
Whether to use strict mode for tool calls. Only applicable when
using certain supported models.
nullable: true
knowledge_base_ids:
type: array
items:
type: string
description: A list of knowledge base ids to use for this resource.
nullable: true
kb_config:
type: object
$ref: "#/components/schemas/KBConfig"
description: Knowledge base configuration for RAG retrieval.
nullable: true
start_speaker:
type: string
enum:
- user
- agent
description:
The speaker who starts the conversation. Required. Must be either
'user' or 'agent'.
begin_after_user_silence_ms:
type: integer
example: 2000
description:
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.
nullable: true
begin_message:
type: string
example: Hey I am a virtual assistant calling from Retell Hospital.
description:
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.
nullable: true
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 one state).
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
nullable: true
starting_state:
type: string
example: information_collection
description:
Name of the starting state. Required if states is not empty.
nullable: true
default_dynamic_variables:
type: object
additionalProperties:
type: string
example:
customer_name: John Doe
description:
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.
nullable: true
version:
type: integer
example: 1
description: The version of the LLM.
nullable: true
mcps:
type: array
items:
$ref: "#/components/schemas/MCP"
description: A list of MCPs to use for this LLM.
nullable: true
ScoringCriteria:
type: object
properties:
custom_conditions:
type: array
items:
type: object
required:
- description
- score_weight
properties:
description:
type: string
score_weight:
type: number
minimum: 1
maximum: 100
performance_metrics:
type: array
items:
$ref: "#/components/schemas/PerformanceMetricCriteria"
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
SmsSender:
oneOf:
- type: object
required:
- type
properties:
type:
type: string
enum:
- current_number
- type: object
required:
- type
properties:
type:
type: string
enum:
- short_code
SmsDestination:
oneOf:
- type: object
required:
- type
properties:
type:
type: string
enum:
- customer_number
- type: object
required:
- type
- phone_number
properties:
type:
type: string
enum:
- phone_number
phone_number:
type: string
description: Destination phone number in E.164 format.
ignore_e164_validation:
type: boolean
description:
If true, skip E.164 validation for this phone number (same
semantics as transfer_call ignore_e164_validation).
SentimentAnalysis:
type: object
required:
- details
- positive_count
- neutral_count
- negative_count
properties:
details:
type: array
items:
oneOf:
- type: object
properties:
duration:
$ref: "#/components/schemas/Duration"
sentiment:
type: string
enum:
- positive
- neutral
- negative
- type: object
properties:
response_id:
type: number
sentiment:
type: string
enum:
- positive
- neutral
- negative
positive_count:
type: number
neutral_count:
type: number
negative_count:
type: number
SkipResponseEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Skip response
description: Must be "Skip response" for skip response edge
AlwaysEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Always
description: Must be "Always" for always edge
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.
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.
SmsContent:
oneOf:
- $ref: "#/components/schemas/SmsContentPredefined"
- $ref: "#/components/schemas/SmsContentInferred"
SmsFailedEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Failed to send
description: Must be "failed to send" for SMS failed edge
SmsNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- instruction
- success_edge
- failed_edge
properties:
type:
type: string
enum:
- sms
description: Type of the node
instruction:
$ref: "#/components/schemas/NodeInstruction"
success_edge:
$ref: "#/components/schemas/SmsSuccessEdge"
failed_edge:
$ref: "#/components/schemas/SmsFailedEdge"
SmsSuccessEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Sent successfully
description: Must be "sent successfully" for SMS success edge
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.
StateTransitionMessage:
type: object
required:
- message_id
- role
- created_timestamp
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- state_transition
description: This is a state transition.
former_state_name:
type: string
description: Former state name
new_state_name:
type: string
description: New state name
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
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
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.
TestCaseBatchJob:
type: object
required:
- test_case_batch_job_id
- status
- response_engine
- pass_count
- fail_count
- error_count
- total_count
- creation_timestamp
- user_modified_timestamp
properties:
test_case_batch_job_id:
type: string
description: Unique identifier for the test case batch job
status:
type: string
enum:
- in_progress
- complete
description: Status of the batch job
response_engine:
$ref: "#/components/schemas/ResponseEngine"
pass_count:
type: integer
description: Number of test cases that passed
minimum: 0
fail_count:
type: integer
description: Number of test cases that failed
minimum: 0
error_count:
type: integer
description: Number of test cases that encountered errors
minimum: 0
total_count:
type: integer
description: Total number of test cases in the batch
minimum: 0
creation_timestamp:
type: integer
description:
Timestamp when the batch job was created (milliseconds since epoch)
user_modified_timestamp:
type: integer
description:
Timestamp when the batch job was last modified (milliseconds since
epoch)
TestCaseDefinitionInput:
type: object
properties:
name:
type: string
description: Name of the test case definition
response_engine:
$ref: "#/components/schemas/RetellResponseEngine"
description:
Response engine to use for the test case. Custom LLM is not
supported.
user_prompt:
type: string
description: User prompt to simulate in the test case
metrics:
type: array
items:
type: string
description: Array of metric names to evaluate
dynamic_variables:
type: object
additionalProperties:
type: string
description: Dynamic variables to inject into the response engine
tool_mocks:
type: array
items:
$ref: "#/components/schemas/ToolMock"
description: Mock tool calls for testing
llm_model:
$ref: "#/components/schemas/LLMModel"
description: LLM model to use for simulation
TestCaseDefinition:
allOf:
- $ref: "#/components/schemas/TestCaseDefinitionInput"
- type: object
required:
- name
- response_engine
- metrics
- user_prompt
- dynamic_variables
- tool_mocks
- llm_model
- test_case_definition_id
- type
- creation_timestamp
- user_modified_timestamp
properties:
test_case_definition_id:
type: string
description: Unique identifier for the test case definition
type:
type: string
enum:
- simulation
description: Type of test case definition
creation_timestamp:
type: integer
description:
Timestamp when the test case definition was created
(milliseconds since epoch)
user_modified_timestamp:
type: integer
description:
Timestamp when the test case definition was last modified
(milliseconds since epoch)
TestCaseJob:
type: object
required:
- test_case_job_id
- status
- test_case_definition_id
- test_case_definition_snapshot
- creation_timestamp
- user_modified_timestamp
properties:
test_case_job_id:
type: string
description: Unique identifier for the test case job
status:
type: string
enum:
- in_progress
- pass
- fail
- error
description: Status of the test case job
test_case_definition_id:
type: string
description: ID of the test case definition used
test_case_definition_snapshot:
$ref: "#/components/schemas/TestCaseDefinition"
description: Snapshot of the test case definition at time of execution
transcript_snapshot:
type: object
nullable: true
description:
Snapshot of the transcript generated during test execution. Can be
either ConversationFlowPlaygroundSnapshot or
MultiStatePromptPlaygroundSnapshot
result_explanation:
type: string
nullable: true
description: Explanation of the test result
creation_timestamp:
type: integer
description:
Timestamp when the test case job was created (milliseconds since
epoch)
user_modified_timestamp:
type: integer
description:
Timestamp when the test case job was last modified (milliseconds
since epoch)
ToolMockInputMatchRule:
oneOf:
- type: object
required:
- type
properties:
type:
type: string
enum:
- any
description: Match any input of the tool
- type: object
required:
- type
- args
properties:
type:
type: string
enum:
- partial_match
description: Match only calls with specific arguments
args:
type: object
additionalProperties: true
description:
Arguments to match. Only provided fields will be checked
ToolMock:
type: object
required:
- tool_name
- input_match_rule
- output
properties:
tool_name:
type: string
description: Name of the tool to mock
input_match_rule:
$ref: "#/components/schemas/ToolMockInputMatchRule"
description: Rule for matching tool calls
output:
type: string
maxLength: 15000
description:
The output of the tool call that will be fed into the LLM. Should be
a JSON string.
result:
type: boolean
nullable: true
description:
For tool calls like transfer_call that require a boolean result.
Optional for most tools.
TimeWindow:
type: object
required:
- start
- end
properties:
start:
type: number
example: 540
description: Start time in minutes since local midnight.
end:
type: number
example: 1020
description: End time in minutes since local midnight.
ToolCallAccuracyAnalysis:
type: object
required:
- details
- tool_call_accurate_utterance_count
- total_utterance_count
properties:
details:
type: array
items:
$ref: "#/components/schemas/UtteranceToolCallAccuracy"
tool_call_accurate_utterance_count:
type: number
total_utterance_count:
type: number
ToolCallInvocationAnalysis:
type: object
required:
- tool_call_average_latency
- tool_call_success_count
- tool_call_total_count
properties:
tool_call_average_latency:
type: number
tool_call_success_count:
type: number
tool_call_total_count:
type: number
ToolCallInvocationMessage:
type: object
required:
- message_id
- role
- tool_call_id
- name
- arguments
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- tool_call_invocation
description: This is a tool call invocation.
tool_call_id:
type: string
description: Tool call id, globally unique.
name:
type: string
description: Name of the function in this tool call.
arguments:
type: string
description:
Arguments for this tool call, it's a stringified JSON object.
thought_signature:
type: string
description:
Optional thought signature from Google Gemini thinking models. This
is used internally to maintain reasoning chain in multi-turn
function calling.
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
ToolCallInvocationUtterance:
type: object
required:
- role
- tool_call_id
- name
- arguments
properties:
role:
type: string
enum:
- tool_call_invocation
description: This is a tool call invocation.
tool_call_id:
type: string
description: Tool call id, globally unique.
name:
type: string
description: Name of the function in this tool call.
arguments:
type: string
description:
Arguments for this tool call, it's a stringified JSON object.
thought_signature:
type: string
description:
Optional thought signature from Google Gemini thinking models. This
is used internally to maintain reasoning chain in multi-turn
function calling.
ToolCallResultMessage:
type: object
required:
- message_id
- role
- tool_call_id
- content
- created_timestamp
properties:
message_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description: Unique id of the message
role:
type: string
enum:
- tool_call_result
description: This is the result of a tool call.
tool_call_id:
type: string
description: Tool call id, globally unique.
content:
type: string
description:
Result of the tool call, can be a string, a stringified json, etc.
successful:
type: boolean
description: Whether the tool call was successful.
created_timestamp:
type: integer
description: Create timestamp of the message
example: 1703302428855
ToolCallResultUtterance:
type: object
required:
- role
- tool_call_id
- content
properties:
role:
type: string
enum:
- tool_call_result
description: This is the result of a tool call.
tool_call_id:
type: string
description: Tool call id, globally unique.
content:
type: string
description:
Result of the tool call, can be a string, a stringified json, etc.
successful:
type: boolean
description: Whether the tool call was successful.
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"
TransferCallNode:
allOf:
- $ref: "#/components/schemas/NodeBase"
- type: object
required:
- type
- transfer_destination
- transfer_option
- edge
properties:
type:
type: string
enum:
- transfer_call
description: Type of the node
transfer_destination:
$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
description: Custom SIP headers for transfer calls
transfer_option:
type: object
$ref: "#/components/schemas/TransferOption"
edge:
$ref: "#/components/schemas/TransferFailedEdge"
speak_during_execution:
type: boolean
description: If true, will speak during execution
instruction:
$ref: "#/components/schemas/NodeInstruction"
description:
What to say when transferring the call, only used when speak
during execution
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
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
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
TransferDestination:
oneOf:
- $ref: "#/components/schemas/TransferDestinationPredefined"
- $ref: "#/components/schemas/TransferDestinationInferred"
TransferFailedEdge:
allOf:
- $ref: "#/components/schemas/NodeEdge"
- type: object
required:
- transition_condition
properties:
transition_condition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
enum:
- Transfer failed
description:
Must be "Transfer failed" for transfer failed edge
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
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
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
TransferOption:
oneOf:
- $ref: "#/components/schemas/TransferOptionColdTransfer"
- $ref: "#/components/schemas/TransferOptionWarmTransfer"
- $ref: "#/components/schemas/TransferOptionAgenticWarmTransfer"
x-mintlify-name: Transfer Options
UpdateOrganizationRequest:
allOf:
- $ref: "#/components/schemas/CreateOrganizationRequest"
- type: object
properties:
outage_mode_enabled:
type: boolean
description: Whether outage mode is enabled
concurrency_burst_enabled:
type: boolean
description:
Whether burst concurrency mode is enabled. When enabled, allows
the org to exceed their normal concurrency limit (up to 3x or
+300, whichever is lower) with a $0.10/min surcharge on burst
calls.
use_stable_server:
type: boolean
description:
Whether to route calls and API requests from this organization
to the stable server cluster (enterprise only). When enabled, a
$0.02/min additional charge will be applied.
UserFormRequest:
type: object
required:
- form
properties:
form:
type: object
additionalProperties:
type: string
description:
A JSON object containing survey form data with string values
utm_parameters:
type: object
additionalProperties:
type: string
description: UTM tracking parameters
referrer:
type: string
description: Referrer URL
UtteranceHallucination:
type: object
required:
- response_id
- hallucinations
properties:
response_id:
type: number
hallucinations:
type: array
items:
$ref: "#/components/schemas/Hallucination"
UtteranceMistranscribedImportantEntities:
type: object
required:
- response_id
- details
properties:
response_id:
type: number
details:
type: array
items:
type: object
properties:
original_transcript:
type: string
corrected_transcript:
type: string
UtteranceNaturalnessIssues:
type: object
required:
- response_id
- naturalness_issues
properties:
response_id:
type: number
naturalness_issues:
type: array
items:
$ref: "#/components/schemas/NaturalnessIssue"
UtteranceOrToolCall:
oneOf:
- $ref: "#/components/schemas/Utterance"
- $ref: "#/components/schemas/ToolCallInvocationUtterance"
- $ref: "#/components/schemas/ToolCallResultUtterance"
- $ref: "#/components/schemas/NodeTransitionUtterance"
- $ref: "#/components/schemas/DTMFUtterance"
UtteranceToolCallAccuracy:
type: object
required:
- response_id
- missed_tool_calls
- incorrectly_added_tool_calls
- wrong_arguments_tool_calls
properties:
response_id:
type: number
missed_tool_calls:
type: array
items:
type: string
incorrectly_added_tool_calls:
type: array
items:
type: string
wrong_arguments_tool_calls:
type: array
items:
type: string
Utterance:
type: object
required:
- role
- content
- words
properties:
role:
type: string
enum:
- agent
- user
- transfer_target
description:
Documents whether this utterance is spoken by agent or user.
example: agent
content:
type: string
description: Transcript of the utterances.
example: hi how are you doing?
words:
type: array
example:
- word: hi
start: 0.7
end: 1.3
description:
Array of words in the utterance with the word timestamp. Useful for
understanding what word was spoken at what time. Note that the word
timestamp is not guaranteed to be accurate, it's more like an
approximation.
items:
type: object
properties:
word:
type: string
description: Word transcript (with punctuation if applicable).
start:
type: number
description:
Start time of the word in the call in second. This is relative
audio time, not wall time.
end:
type: number
description:
End time of the word in the call in second. This is relative
audio time, not wall time.
V2CallBase:
type: object
required:
- call_id
- agent_id
- agent_version
- call_status
properties:
call_id:
type: string
example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6
description:
Unique id of the call. Used to identify the call in the LLM
websocket and used to authenticate in the audio websocket.
agent_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Corresponding agent id of this call.
agent_name:
type: string
example: My Agent
description: Name of the agent.
agent_version:
type: integer
example: 1
description: The version of the agent.
call_status:
type: string
enum:
- registered
- not_connected
- ongoing
- ended
- error
example: registered
description: |
Status of call.
- `registered`: Call id issued, starting to make a call using this id.
- `ongoing`: Call connected and ongoing.
- `ended`: The underlying websocket has ended for the call. Either user or agent hung up, or call transferred.
- `error`: Call encountered error.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put anything
here like your internal customer id associated with the call. Not
used for processing. You can later get this field from the call
object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string that
injects into your Response Engine prompt and tool description. Only
applicable for Response Engine.
collected_dynamic_variables:
type: object
additionalProperties: {}
example:
last_node_name: Test node
description:
Dynamic variables collected from the call. Only available after the
call ends.
custom_sip_headers:
type: object
additionalProperties:
type: string
description: Custom SIP headers to be added to the call.
example:
X-Custom-Header: Custom Value
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
example: everything
description:
Data storage setting for this call's agent. "everything" stores all
data, "everything_except_pii" excludes PII when possible,
"basic_attributes_only" stores only metadata.
nullable: true
opt_in_signed_url:
type: boolean
example: true
description:
Whether this agent opts in for signed URLs for public logs and
recordings. When enabled, the generated URLs will include security
signatures that restrict access and automatically expire after 24
hours.
start_timestamp:
type: integer
example: 1703302407333
description:
Begin timestamp (milliseconds since epoch) of the call. Available
after call starts.
end_timestamp:
type: integer
example: 1703302428855
description:
End timestamp (milliseconds since epoch) of the call. Available
after call ends.
transfer_end_timestamp:
type: integer
example: 1703302628855
description:
Transfer end timestamp (milliseconds since epoch) of the call.
Available after transfer call ends.
duration_ms:
type: integer
example: 10000
description:
Duration of the call in milliseconds. Available after call ends.
transcript:
type: string
example: |
Agent: hi how are you doing?
User: Doing pretty well. How are you?
Agent: That's great to hear! I'm doing well too, thanks! What's up?
User: I don't have anything in particular.
Agent: Got it, just checking in!
User: Alright. See you.
Agent: have a nice day
description: Transcription of the call. Available after call ends.
transcript_object:
type: array
items:
$ref: "#/components/schemas/Utterance"
description:
Transcript of the call in the format of a list of utterance, with
timestamp. Available after call ends.
transcript_with_tool_calls:
type: array
items:
$ref: "#/components/schemas/UtteranceOrToolCall"
description:
Transcript of the call weaved with tool call invocation and results.
It precisely captures when (at what utterance, which word) the tool
was invoked and what was the result. Available after call ends.
scrubbed_transcript_with_tool_calls:
type: array
items:
$ref: "#/components/schemas/UtteranceOrToolCall"
description:
Transcript of the call weaved with tool call invocation and results,
without PII. It precisely captures when (at what utterance, which
word) the tool was invoked and what was the result. Available after
call ends.
recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description: Recording of the call. Available after call ends.
recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description:
Recording of the call, with each party's audio stored in a separate
channel. Available after the call ends.
scrubbed_recording_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav
description:
Recording of the call without PII. Available after call ends.
scrubbed_recording_multi_channel_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav
description:
Recording of the call without PII, with each party's audio stored in
a separate channel. Available after the call ends.
public_log_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt
description:
Public log of the call, containing details about all the requests
and responses received in LLM WebSocket, latency tracking for each
turntaking, helpful for debugging and tracing. Available after call
ends.
knowledge_base_retrieved_contents_url:
type: string
example: https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt
description:
URL to the knowledge base retrieved contents of the call. Available
after call ends if the call utilizes knowledge base feature. It
consists of the respond id and the retrieved contents related to
that response. It's already rendered in call history tab of
dashboard, and you can also manually download and check against the
transcript to view the knowledge base retrieval results.
latency:
type: object
description:
Latency tracking of the call, available after call ends. Not all
fields here will be available, as it depends on the type of call and
feature used.
properties:
e2e:
description:
End to end latency (from user stops talking to agent start
talking) tracking of the call. This latency does not account for
the network trip time from Retell server to user frontend. The
latency is tracked every time turn change between user and
agent.
$ref: "#/components/schemas/CallLatency"
asr:
description:
Transcription latency (diff between the duration of the chunks
streamed and the durations of the transcribed part) tracking of
the call.
$ref: "#/components/schemas/CallLatency"
llm:
description:
LLM latency (from issue of LLM call to first speakable chunk
received) tracking of the call. When using custom LLM. this
latency includes LLM websocket roundtrip time between user
server and Retell server.
$ref: "#/components/schemas/CallLatency"
llm_websocket_network_rtt:
description:
LLM websocket roundtrip latency (between user server and Retell
server) tracking of the call. Only populated for calls using
custom LLM.
$ref: "#/components/schemas/CallLatency"
tts:
description:
Text-to-speech latency (from the triggering of TTS to first byte
received) tracking of the call.
$ref: "#/components/schemas/CallLatency"
knowledge_base:
description:
Knowledge base latency (from the triggering of knowledge base
retrival to all relevant context received) tracking of the call.
Only populated when using knowledge base feature for the agent
of the call.
$ref: "#/components/schemas/CallLatency"
s2s:
description:
Speech-to-speech latency (from requesting responses of a S2S
model to first byte received) tracking of the call. Only
populated for calls that uses S2S model like Realtime API.
$ref: "#/components/schemas/CallLatency"
disconnection_reason:
$ref: "#/components/schemas/DisconnectionReason"
example: agent_hangup
description:
The reason for the disconnection of the call. Read detailed
description about reasons listed here at [Disconnection Reason
Doc](/reliability/debug-call-disconnect#understanding-disconnection-reasons).
transfer_destination:
type: string
example: "+12137771234"
description:
The destination number or identifier where the call was transferred
to. Only populated when the disconnection reason was
`call_transfer`. Can be a phone number or a SIP URI. SIP URIs are
prefixed with "sip:" and may include a ";transport=..." portion (if
transport is known) where the transport type can be "tls", "tcp" or
"udp".
nullable: true
call_analysis:
description:
Post call analysis that includes information such as sentiment,
status, summary, and custom defined data to extract. Available after
call ends. Subscribe to `call_analyzed` webhook event type to
receive it once ready.
$ref: "#/components/schemas/CallAnalysis"
call_cost:
description:
Cost of the call, including all the products and their costs and
discount.
type: object
required:
- product_costs
- total_duration_seconds
- total_duration_unit_price
- combined_cost
properties:
product_costs:
type: array
description:
List of products with their unit prices and costs in cents
items:
$ref: "#/components/schemas/ProductCost"
total_duration_seconds:
type: number
description: Total duration of the call in seconds
example: 60
total_duration_unit_price:
type: number
description:
Total unit duration price of all products in cents per second
example: 1
combined_cost:
type: number
description: Combined cost of all individual costs in cents
example: 70
llm_token_usage:
type: object
description:
LLM token usage of the call, available after call ends. Not
populated if using custom LLM, realtime API, or no LLM call is made.
required:
- values
- average
- num_requests
properties:
values:
type: array
items:
type: number
description: All the token count values in the call.
average:
type: number
description: Average token count of the call.
num_requests:
type: number
description: Number of requests made to the LLM.
V2CallResponse:
oneOf:
- $ref: "#/components/schemas/V2WebCallResponse"
- $ref: "#/components/schemas/V2PhoneCallResponse"
V2PhoneCallResponse:
allOf:
- type: object
required:
- call_type
- from_number
- to_number
- direction
properties:
call_type:
type: string
enum:
- phone_call
example: phone_call
description:
Type of the call. Used to distinguish between web call and phone
call.
from_number:
type: string
example: "+12137771234"
description: The caller number.
to_number:
type: string
example: "+12137771235"
description: The callee number.
direction:
type: string
enum:
- inbound
- outbound
example: inbound
description: Direction of the phone call.
telephony_identifier:
type: object
description:
Telephony identifier of the call, populated when available.
Tracking purposes only.
properties:
twilio_call_sid:
type: string
example: CA5d0d0d8047bf685c3f0ff980fe62c123
description: Twilio call sid.
- $ref: "#/components/schemas/V2CallBase"
V2WebCallResponse:
allOf:
- type: object
required:
- call_type
- access_token
properties:
call_type:
type: string
enum:
- web_call
example: web_call
description:
Type of the call. Used to distinguish between web call and phone
call.
access_token:
type: string
example: eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p
description:
Access token to enter the web call room. This needs to be passed
to your frontend to join the call.
- $ref: "#/components/schemas/V2CallBase"
VoiceResponse:
type: object
required:
- voice_id
- voice_name
- provider
- gender
properties:
voice_id:
type: string
example: retell-Cimo
description: Unique id for the voice.
voice_name:
type: string
example: Adrian
description: Name of the voice.
provider:
type: string
enum:
- elevenlabs
- openai
- deepgram
- cartesia
- minimax
- fish_audio
- platform
example: elevenlabs
description: Indicates the provider of voice.
accent:
type: string
example: American
description: Accent annotation of the voice.
gender:
type: string
enum:
- male
- female
example: male
description: Gender of voice.
age:
type: string
example: Young
description: Age annotation of the voice.
preview_audio_url:
type: string
example: https://retell-utils-public.s3.us-west-2.amazonaws.com/adrian.mp3
description: URL to the preview audio of the voice.
VoicemailActionBridgeTransfer:
type: object
properties:
type:
type: string
enum:
- bridge_transfer
example: bridge_transfer
required:
- type
VoicemailActionHangup:
type: object
properties:
type:
type: string
enum:
- hangup
example: hangup
required:
- type
VoicemailActionPrompt:
type: object
properties:
type:
type: string
enum:
- prompt
example: prompt
text:
type: string
example: Summarize the call in 2 sentences.
description:
The prompt used to generate the text to be spoken when the call is
detected to be in voicemail.
required:
- type
- text
VoicemailActionStaticText:
type: object
properties:
type:
type: string
enum:
- static_text
example: static_text
text:
type: string
example: Please give us a callback tomorrow at 10am.
description:
The text to be spoken when the call is detected to be in voicemail.
required:
- type
- text
VoicemailAction:
oneOf:
- $ref: "#/components/schemas/VoicemailActionPrompt"
- $ref: "#/components/schemas/VoicemailActionStaticText"
- $ref: "#/components/schemas/VoicemailActionHangup"
- $ref: "#/components/schemas/VoicemailActionBridgeTransfer"
IvrActionHangup:
type: object
properties:
type:
type: string
enum:
- hangup
example: hangup
required:
- type
IvrAction:
oneOf:
- $ref: "#/components/schemas/IvrActionHangup"
WER:
type: object
required:
- word_count
- number_deletions
- number_insertions
- number_substitutions
properties:
word_count:
type: number
number_deletions:
type: number
number_insertions:
type: number
number_substitutions:
type: number
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.
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.
security:
- api_key: []
paths:
/add-knowledge-base-sources/{knowledge_base_id}:
post:
description: Add sources to a knowledge base
operationId: addKnowledgeBaseSources
parameters:
- in: path
name: knowledge_base_id
schema:
type: string
example: kb_1234567890
required: true
description: The knowledge base id to delete source from.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/KnowledgeBaseAddSourcesRequest"
responses:
"201":
description: Successfully created a new knowledge base.
content:
application/json:
schema:
$ref: "#/components/schemas/KnowledgeBaseResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-agent:
post:
description: Create a new agent
operationId: createAgent
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/AgentRequest"
- required:
- response_engine
- voice_id
responses:
"201":
description: Successfully created a new agent.
content:
application/json:
schema:
$ref: "#/components/schemas/AgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/create-batch-call:
post:
description: Create a batch call
operationId: createBatchCall
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from_number
- tasks
properties:
name:
type: string
example: First batch call
description:
The name of the batch call. Only used for your own
reference.
trigger_timestamp:
type: number
example: 1735718400000
description:
The scheduled time for sending the batch call, represented
as a Unix timestamp in milliseconds. If omitted, the call
will be sent immediately.
from_number:
type: string
minLength: 1
example: "+14157774444"
description:
The number you own in E.164 format. Must be a number
purchased from Retell or imported to Retell.
reserved_concurrency:
type: integer
minimum: 0
description:
Number of concurrency reserved for all other calls that are
not triggered by batch calls, such as inbound calls.
tasks:
type: array
description:
A list of individual call tasks to be executed as part of
the batch call. Each task represents a single outbound call
and includes details such as the recipient's phone number
and optional dynamic variables to personalize the call
content.
items:
$ref: "#/components/schemas/BatchCallTask"
call_time_window:
$ref: "#/components/schemas/CallTimeWindow"
responses:
"201":
description: Successfully created a batch call.
content:
application/json:
schema:
$ref: "#/components/schemas/BatchCallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/create-batch-test:
post:
description: Create a batch test to run multiple test cases
operationId: createBatchTest
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- test_case_definition_ids
- response_engine
properties:
test_case_definition_ids:
type: array
minItems: 1
maxItems: 1000
items:
type: string
description: Array of test case definition IDs to run
response_engine:
$ref: "#/components/schemas/RetellResponseEngine"
description:
Response engine to use for the test cases. Custom LLM is not
supported.
responses:
"201":
description: Test case batch job created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseBatchJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-test-case-definition:
post:
description: Create a new test case definition
operationId: createTestCaseDefinition
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/TestCaseDefinitionInput"
- type: object
required:
- name
- response_engine
- user_prompt
- metrics
responses:
"201":
description: Test case definition created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-test-case-definition/{test_case_definition_id}:
delete:
description: Delete a test case definition
operationId: deleteTestCaseDefinition
parameters:
- in: path
name: test_case_definition_id
schema:
type: string
required: true
description: ID of the test case definition to delete
responses:
"204":
description: Test case definition deleted successfully
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-test-case-definition/{test_case_definition_id}:
get:
description: Get a test case definition by ID
operationId: getTestCaseDefinition
parameters:
- in: path
name: test_case_definition_id
schema:
type: string
required: true
description: ID of the test case definition to retrieve
responses:
"200":
description: Test case definition retrieved successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-test-case-definitions:
get:
description: List test case definitions for a response engine
operationId: listTestCaseDefinitions
parameters:
- in: query
name: type
schema:
type: string
enum:
- retell-llm
- conversation-flow
required: true
description: Type of response engine
- in: query
name: llm_id
schema:
type: string
description: LLM ID (required when type is retell-llm)
- in: query
name: conversation_flow_id
schema:
type: string
description:
Conversation flow ID (required when type is conversation-flow)
- in: query
name: version
schema:
type: integer
description: Version of the response engine (defaults to latest)
responses:
"200":
description: Test case definitions retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TestCaseDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-test-case-definitions:
get:
description: List test case definitions with pagination
operationId: listTestCaseDefinitionsV2
parameters:
- in: query
name: type
schema:
type: string
enum:
- retell-llm
- conversation-flow
required: true
description: Type of response engine
- in: query
name: llm_id
schema:
type: string
description: LLM ID (required when type is retell-llm)
- in: query
name: conversation_flow_id
schema:
type: string
description:
Conversation flow ID (required when type is conversation-flow)
- in: query
name: version
schema:
type: integer
description: Version of the response engine (defaults to latest)
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Test case definitions retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/TestCaseDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/update-test-case-definition/{test_case_definition_id}:
put:
description: Update a test case definition
operationId: updateTestCaseDefinition
parameters:
- in: path
name: test_case_definition_id
schema:
type: string
required: true
description: ID of the test case definition to update
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseDefinitionInput"
responses:
"200":
description: Test case definition updated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-batch-test/{test_case_batch_job_id}:
get:
description: Get a batch test job by ID
operationId: getBatchTest
parameters:
- in: path
name: test_case_batch_job_id
schema:
type: string
required: true
description: ID of the batch test job to retrieve
responses:
"200":
description: Batch test job retrieved successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseBatchJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-batch-tests:
get:
description: List batch test jobs for a response engine
operationId: listBatchTests
parameters:
- in: query
name: type
schema:
type: string
enum:
- retell-llm
- conversation-flow
required: true
description: Type of response engine
- in: query
name: llm_id
schema:
type: string
description: LLM ID (required when type is retell-llm)
- in: query
name: conversation_flow_id
schema:
type: string
description:
Conversation flow ID (required when type is conversation-flow)
- in: query
name: version
schema:
type: integer
description: Version of the response engine (defaults to latest)
responses:
"200":
description: Batch test jobs retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TestCaseBatchJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-batch-tests:
get:
description: List batch test jobs with pagination
operationId: listBatchTestsV2
parameters:
- in: query
name: type
schema:
type: string
enum:
- retell-llm
- conversation-flow
required: true
description: Type of response engine
- in: query
name: llm_id
schema:
type: string
description: LLM ID (required when type is retell-llm)
- in: query
name: conversation_flow_id
schema:
type: string
description:
Conversation flow ID (required when type is conversation-flow)
- in: query
name: version
schema:
type: integer
description: Version of the response engine (defaults to latest)
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Batch test jobs retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/TestCaseBatchJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-test-run/{test_case_job_id}:
get:
description: Get a test case job (test run) by ID
operationId: getTestRun
parameters:
- in: path
name: test_case_job_id
schema:
type: string
required: true
description: ID of the test case job to retrieve
responses:
"200":
description: Test case job retrieved successfully
content:
application/json:
schema:
$ref: "#/components/schemas/TestCaseJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-test-runs/{test_case_batch_job_id}:
get:
description: List all test case jobs (test runs) for a batch test job
operationId: listTestRuns
parameters:
- in: path
name: test_case_batch_job_id
schema:
type: string
required: true
description: ID of the batch test job
responses:
"200":
description: Test case jobs retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TestCaseJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-test-runs/{test_case_batch_job_id}:
get:
description:
List test case jobs (test runs) for a batch test job with pagination
operationId: listTestRunsV2
parameters:
- in: path
name: test_case_batch_job_id
schema:
type: string
required: true
description: ID of the batch test job
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Test case jobs retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/TestCaseJob"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-chat-agent:
post:
description: Create a new chat agent
operationId: createChatAgent
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ChatAgentRequest"
- required:
- response_engine
responses:
"201":
description: Successfully created a new chat agent.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatAgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"500":
$ref: "#/components/responses/InternalServerError"
/create-chat-completion:
post:
description: Create a chat completion message
operationId: createChatCompletion
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- chat_id
- content
properties:
chat_id:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: Unique id of the chat to create completion.
content:
type: string
example: hi how are you doing?
description: user message to generate agent chat completion.
responses:
"201":
description: Successfully created chat completion.
content:
application/json:
schema:
type: object
required:
- messages
properties:
messages:
type: array
items:
$ref: "#/components/schemas/MessageOrToolCall"
description:
New messages generated by the agent during this
completion, including any tool call invocations and their
results. Does not include the original input messages.
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-chat:
post:
description: Create a chat session
operationId: createChat
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
properties:
agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: The chat agent to use for the call.
agent_version:
type: integer
example: 1
description:
The version of the chat agent to use for the chat. If not
provided, will default to latest version.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the chat. Not used for processing. You can later get this
field from the chat object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string
that injects into your Response Engine prompt and tool
description. Only applicable for Response Engine.
responses:
"201":
description: Successfully registered a phone call.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-conversation-flow-component:
post:
description: Create a new shared conversation flow component
operationId: createConversationFlowComponent
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateConversationFlowComponentRequest"
responses:
"201":
description: Successfully created conversation flow component
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowComponentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-conversation-flow:
post:
description:
Create a new Conversation Flow that can be attached to an agent. This is
used to generate response output for the agent.
operationId: createConversationFlow
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateConversationFlowRequest"
responses:
"201":
description: Successfully created a conversation flow
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-knowledge-base:
post:
description: Create a new knowledge base
operationId: createKnowledgeBase
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/KnowledgeBaseRequest"
responses:
"201":
description: Successfully created a new knowledge base.
content:
application/json:
schema:
$ref: "#/components/schemas/KnowledgeBaseResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/create-phone-number:
post:
description: Buy a new phone number & Bind agents
operationId: createPhoneNumber
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
inbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when receiving inbound calls. If
null, this number would not accept inbound call. Deprecated.
See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when conducting outbound calls.
If null, this number would not be able to initiate outbound
call without agent id override. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agent_version:
type: integer
example: 1
description:
Version of the inbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_version:
type: integer
example: 1
description:
Version of the outbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
inbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to inbound_agent_id.
nullable: true
outbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
outbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to outbound_agent_id.
nullable: true
area_code:
type: integer
example: 415
description:
Area code of the number to obtain. Format is a 3 digit
integer. Currently only supports US area code.
nickname:
type: string
example: Frontdesk Number
description:
Nickname of the number. This is for your reference only.
inbound_webhook_url:
type: string
example: https://example.com/inbound-webhook
description:
If set, will send a webhook for inbound calls, where you can
to override agent id, set dynamic variables and other fields
specific to that call.
nullable: true
allowed_inbound_country_list:
type: array
items:
type: string
example: ["US", "CA", "GB"]
description:
List of ISO 3166-1 alpha-2 country codes from which inbound
calls are allowed. If not set or empty, calls from all
countries are allowed.
nullable: true
allowed_outbound_country_list:
type: array
items:
type: string
example: ["US", "CA"]
description:
List of ISO 3166-1 alpha-2 country codes to which outbound
calls are allowed. If not set or empty, calls to all
countries are allowed.
nullable: true
number_provider:
type: string
enum:
- twilio
- telnyx
example: twilio
description:
The provider to purchase the phone number from. Default to
twilio.
country_code:
type: string
enum:
- US
- CA
example: US
description:
The ISO 3166-1 alpha-2 country code of the number you are
trying to purchase. If left empty, will default to "US".
toll_free:
type: boolean
description:
Whether to purchase a toll-free number. Toll-free numbers
incur higher costs.
phone_number:
type: string
minLength: 1
example: "+14157774444"
description:
The number you are trying to purchase in E.164 format of the
number (+country code then number with no space and no
special characters).
transport:
type: string
example: "TCP"
description:
Outbound transport protocol to use for the phone number.
Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
nullable: true
fallback_number:
type: string
example: "+14155551234"
description:
Enterprise only. Phone number to transfer inbound calls to
when organization is in outage mode. Can be either a Retell
phone number or an external number. Cannot be the same as
this phone number, and cannot be a number that already has
its own fallback configured (prevents nested forwarding).
nullable: true
responses:
"201":
description: Successfully created a new number.
content:
application/json:
schema:
$ref: "#/components/schemas/PhoneNumberResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/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"
/create-sms-chat:
post:
description:
Start an outbound SMS chat conversation with a phone number using the
specified agent. The agent must be configured for chat mode. The initial
SMS message will be automatically generated and sent based on the
agent's configuration.
operationId: createSmsChat
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from_number
- to_number
properties:
from_number:
type: string
minLength: 1
description:
The phone number to send SMS from in E.164 format. Must be a
number purchased from Retell or imported to Retell with SMS
capability.
example: "+12137771234"
to_number:
type: string
minLength: 1
description: The phone number to send SMS to in E.164 format
example: "+14155551234"
override_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
For this particular chat, override the agent used with this
agent id. This does not bind the agent to this number, this
is for one time override.
override_agent_version:
type: integer
example: 1
description:
For this particular chat, override the agent version used
with this version. This does not bind the agent version to
this number, this is for one time override.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the chat. Not used for processing. You can later get this
field from the chat object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string
that injects into your Response Engine prompt and tool
description. Only applicable for Response Engine.
responses:
"200":
description: SMS chat created and initial message sent successfully
content:
application/json:
schema:
$ref: "#/components/schemas/ChatResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-agent/{agent_id}:
delete:
description: Delete an existing agent
operationId: deleteAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
required: true
description:
Unique id of the agent to be deleted. Deletes all versions of the
agent.
responses:
"204":
description: No Content
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-chat-agent/{agent_id}:
delete:
description: Delete an existing chat agent
operationId: deleteChatAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
required: true
description:
Unique id of the chat agent to be deleted. Deletes all versions of
the chat agent.
responses:
"204":
description: No Content
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-conversation-flow-component/{conversation_flow_component_id}:
delete:
description:
Delete a shared conversation flow component. When deleting a shared
component, creates local copies for all linked conversation flows.
operationId: deleteConversationFlowComponent
parameters:
- in: path
name: conversation_flow_component_id
schema:
type: string
required: true
description: ID of the component to delete
responses:
"204":
description: Successfully deleted conversation flow component
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-conversation-flow/{conversation_flow_id}:
delete:
description: Delete a conversation flow and all its versions
operationId: deleteConversationFlow
parameters:
- in: path
name: conversation_flow_id
schema:
type: string
required: true
description: Unique id of the conversation flow to be deleted.
responses:
"204":
description: Successfully deleted the conversation flow
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-knowledge-base-source/{knowledge_base_id}/source/{source_id}:
delete:
description: Delete an existing source from knowledge base
operationId: deleteKnowledgeBaseSource
parameters:
- in: path
name: knowledge_base_id
schema:
type: string
example: kb_1234567890
required: true
description: The knowledge base id to delete source from.
- in: path
name: source_id
schema:
type: string
example: source_1234567890
required: true
description: The source id to delete.
responses:
"200":
description: Successfully deleted a source from a knowledge base.
content:
application/json:
schema:
$ref: "#/components/schemas/KnowledgeBaseResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-knowledge-base/{knowledge_base_id}:
delete:
description: Delete an existing knowledge base
operationId: deleteKnowledgeBase
parameters:
- in: path
name: knowledge_base_id
schema:
type: string
example: kb_1234567890
required: true
description: The knowledge base id to delete.
responses:
"204":
description: No Content
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-phone-number/{phone_number}:
delete:
description: Delete an existing phone number
operationId: deletePhoneNumber
parameters:
- in: path
name: phone_number
schema:
type: string
minLength: 1
example: "+14157774444"
required: true
description:
E.164 format of the number (+country code, then number with no
space, no special characters), used as the unique identifier for
phone number APIs.
responses:
"204":
description: No Content
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/delete-retell-llm/{llm_id}:
delete:
description: Delete an existing Retell LLM Response Engine
operationId: deleteRetellLLM
parameters:
- in: path
name: llm_id
schema:
type: string
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
required: true
description:
Unique id of the Retell LLM Response Engine to be deleted. Deletes
all versions of the Retell LLM Response Engine.
responses:
"204":
description: No Content
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/end-chat/{chat_id}:
patch:
description: End an ongoing chat
operationId: endChat
parameters:
- in: path
name: chat_id
schema:
type: string
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat to be ended
responses:
"204":
description: No Content
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-agent-versions/{agent_id}:
get:
description: Get all versions of an agent
operationId: getAgentVersions
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the agent versions to be retrieved.
responses:
"200":
description: Successfully retrieved all versions of an agent.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-agent/{agent_id}:
get:
description: Retrieve details of a specific agent
operationId: getAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the agent to be retrieved.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. If not
provided, will default to latest version.
responses:
"200":
description: Successfully retrieved an agent.
content:
application/json:
schema:
$ref: "#/components/schemas/AgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-chat-agent-versions/{agent_id}:
get:
description: Get all versions of a chat agent
operationId: getChatAgentVersions
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat agent versions to be retrieved.
responses:
"200":
description: Successfully retrieved all versions of a chat agent.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ChatAgentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-chat-agent/{agent_id}:
get:
description: Retrieve details of a specific chat agent
operationId: getChatAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat agent to be retrieved.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. If not
provided, will default to latest version.
responses:
"200":
description: Successfully retrieved the chat agent.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatAgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-chat/{chat_id}:
get:
description: Retrieve details of a specific chat
operationId: getChat
parameters:
- in: path
name: chat_id
schema:
type: string
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat to be retrieved
responses:
"200":
description: Successfully retrieved an chat.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-concurrency:
get:
description: Get the current concurrency and concurrency limit of the org
operationId: getConcurrency
responses:
"200":
description: Successfully retrieved a voice.
content:
application/json:
schema:
type: object
properties:
current_concurrency:
type: integer
example: 10
description:
The current concurrency (amount of ongoing calls) of the
org.
concurrency_limit:
type: integer
example: 100
description:
The total concurrency limit (at max how many ongoing calls
one can make) of the org. This should be the sum of
`base_concurrency` and `purchased_concurrency`.
base_concurrency:
type: integer
example: 20
description: The free concurrency limit of the org.
purchased_concurrency:
type: integer
example: 80
description:
The amount of concurrency that the org has already
purchased.
concurrency_purchase_limit:
type: integer
example: 100
description:
The maximum amount of concurrency that the org can
purchase.
remaining_purchase_limit:
type: integer
example: 20
description:
The remaining amount of concurrency that the org can
purchase. This is the difference between
`concurrency_purchase_limit` and `purchased_concurrency`.
concurrency_burst_enabled:
type: boolean
example: true
description:
Whether burst concurrency mode is enabled. When enabled,
allows the org to exceed their normal concurrency limit
with a surcharge.
concurrency_burst_limit:
type: integer
example: 60
readOnly: true
description:
The maximum concurrency limit when burst mode is enabled.
This is calculated as min(3x normal limit, normal limit +
300). Returns 0 if burst mode is disabled.
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/get-conversation-flow-component/{conversation_flow_component_id}:
get:
description: Get a shared conversation flow component
operationId: getConversationFlowComponent
parameters:
- in: path
name: conversation_flow_component_id
schema:
type: string
required: true
description: ID of the component to retrieve
responses:
"200":
description: Successfully retrieved conversation flow component
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowComponentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-conversation-flow/{conversation_flow_id}:
get:
description: Retrieve details of a specific Conversation Flow
operationId: getConversationFlow
parameters:
- in: path
name: conversation_flow_id
schema:
type: string
required: true
description: Unique id of the conversation flow to be retrieved.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the conversation flow to retrieve. Default to
latest version.
responses:
"200":
description: Successfully retrieved the conversation flow
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-knowledge-base/{knowledge_base_id}:
get:
description: Retrieve details of a specific knowledge base
operationId: getKnowledgeBase
parameters:
- in: path
name: knowledge_base_id
schema:
type: string
example: kb_1234567890
required: true
description: The knowledge base id to retrieve.
responses:
"200":
description: Successfully retrieved a knowledge base.
content:
application/json:
schema:
$ref: "#/components/schemas/KnowledgeBaseResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/get-mcp-tools/{agent_id}:
get:
description: Get MCP tools for a specific agent
operationId: getMCPTools
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
required: true
description: Unique id of the agent to get MCP tools for.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the agent to use for this request. Default to
latest version.
- in: query
name: mcp_id
schema:
type: string
example: mcp-server-1
required: true
description: The ID of the MCP server to get tools from.
- in: query
name: component_id
schema:
type: string
example: component-123
required: false
description:
The ID of the component if the MCP server is configured under a
component.
responses:
"200":
description: Successfully retrieved MCP tools.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/MCPToolDefinition"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-phone-number/{phone_number}:
get:
description: Retrieve details of a specific phone number
operationId: getPhoneNumber
parameters:
- in: path
name: phone_number
schema:
type: string
minLength: 1
example: "+14157774444"
required: true
description:
E.164 format of the number (+country code, then number with no
space, no special characters), used as the unique identifier for
phone number APIs.
responses:
"200":
description: Successfully retrieved a phone number.
content:
application/json:
schema:
$ref: "#/components/schemas/PhoneNumberResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-retell-llm/{llm_id}:
get:
description: Retrieve details of a specific Retell LLM Response Engine
operationId: getRetellLLM
parameters:
- in: path
name: llm_id
schema:
type: string
example: 16b980523634a6dc504898cda492e939
required: true
description:
Unique id of the Retell LLM Response Engine to be retrieved.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. Default to
latest version.
responses:
"200":
description: Successfully retrieved an Retell LLM Response Engine.
content:
application/json:
schema:
$ref: "#/components/schemas/RetellLLMResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/get-voice/{voice_id}:
get:
description: Retrieve details of a specific voice
operationId: getVoice
parameters:
- in: path
name: voice_id
schema:
type: string
example: retell-Cimo
required: true
description: Unique id for the voice.
responses:
"200":
description: Successfully retrieved a voice.
content:
application/json:
schema:
$ref: "#/components/schemas/VoiceResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/clone-voice:
post:
description: Clone a voice from audio files
operationId: cloneVoice
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- files
- voice_name
- voice_provider
properties:
files:
type: array
items:
type: string
format: binary
description:
Audio files to use for voice cloning. Up to 25 files
allowed. For Cartesia and MiniMax, only 1 file is supported.
For Inworld, up to 3 files are supported.
voice_name:
type: string
minLength: 1
maxLength: 200
description: Name for the cloned voice
voice_provider:
type: string
enum:
- elevenlabs
- cartesia
- minimax
- fish_audio
- platform
description: Voice provider to use for cloning.
responses:
"201":
description: Voice cloned successfully
content:
application/json:
schema:
$ref: "#/components/schemas/VoiceResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/add-community-voice:
post:
description: Add a community voice to the voice library
operationId: addCommunityVoice
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- provider_voice_id
- voice_name
properties:
voice_provider:
type: string
enum:
- elevenlabs
- cartesia
- minimax
- fish_audio
description: Voice provider to add the voice from.
provider_voice_id:
type: string
description: Voice id assigned by the provider.
voice_name:
type: string
minLength: 1
maxLength: 200
description: A custom name for the voice.
public_user_id:
type: string
description:
Required for ElevenLabs only. User id of the voice owner.
responses:
"200":
description: Community voice added successfully
content:
application/json:
schema:
$ref: "#/components/schemas/VoiceResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/search-community-voice:
post:
description: Search for community voices from voice providers
operationId: searchCommunityVoice
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- search_query
properties:
voice_provider:
type: string
enum:
- elevenlabs
- cartesia
- minimax
- fish_audio
description: Voice provider to search.
search_query:
type: string
description:
Search query to find voices by name, description, or ID.
responses:
"200":
description: Community voices retrieved successfully
content:
application/json:
schema:
type: object
required:
- voices
properties:
voices:
type: array
items:
type: object
description: Voices retrieved from the provider.
properties:
provider_voice_id:
type: string
description: id of the voice from the provider.
name:
type: string
description: Name of the voice.
description:
type: string
description: Description of the voice.
public_user_id:
type: string
description:
For elevenlabs only. User id of the voice owner.
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/import-phone-number:
post:
description: Import a phone number from custom telephony & Bind agents
operationId: importPhoneNumber
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone_number
- termination_uri
properties:
phone_number:
type: string
minLength: 1
example: "+14157774444"
description:
The number you are trying to import in E.164 format of the
number (+country code, then number with no space, no special
characters), used as the unique identifier for phone number
APIs.
ignore_e164_validation:
type: boolean
description:
If true, E.164 validation for phone_number is skipped. This
is useful for internal pseudo numbers when using custom
telephony. If omitted, default is true. Must be a boolean
literal; string values like "true" or "false" are invalid.
example: true
termination_uri:
type: string
example: someuri.pstn.twilio.com
description:
The termination uri to uniquely identify your elastic SIP
trunk. This is used for outbound calls. For Twilio elastic
SIP trunks it always end with ".pstn.twilio.com".
sip_trunk_auth_username:
type: string
example: username
description:
The username used for authentication for the SIP trunk.
sip_trunk_auth_password:
type: string
example: "123456"
description:
The password used for authentication for the SIP trunk.
inbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when receiving inbound calls. If
null, this number would not accept inbound call. Deprecated.
See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when conducting outbound calls.
If null, this number would not be able to initiate outbound
call without agent id override. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agent_version:
type: integer
example: 1
description:
Version of the inbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_version:
type: integer
example: 1
description:
Version of the outbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
inbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to inbound_agent_id.
nullable: true
outbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
outbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to outbound_agent_id.
nullable: true
nickname:
type: string
example: Frontdesk Number
description:
Nickname of the number. This is for your reference only.
inbound_webhook_url:
type: string
example: https://example.com/inbound-webhook
description:
If set, will send a webhook for inbound calls, where you can
to override agent id, set dynamic variables and other fields
specific to that call.
nullable: true
allowed_inbound_country_list:
type: array
items:
type: string
example: ["US", "CA", "GB"]
description:
List of ISO 3166-1 alpha-2 country codes from which inbound
calls are allowed. If not set or empty, calls from all
countries are allowed.
nullable: true
allowed_outbound_country_list:
type: array
items:
type: string
example: ["US", "CA"]
description:
List of ISO 3166-1 alpha-2 country codes to which outbound
calls are allowed. If not set or empty, calls to all
countries are allowed.
nullable: true
transport:
type: string
example: "TCP"
description:
Outbound transport protocol to update for the phone number.
Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
nullable: true
responses:
"201":
description: Successfully imported a number.
content:
application/json:
schema:
$ref: "#/components/schemas/PhoneNumberResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-agents:
get:
description: List all agents
operationId: listAgents
parameters:
- in: query
name: limit
schema:
type: integer
example: 50
required: false
description:
A limit on the number of objects to be returned. Limit can range
between 1 and 1000, and the default is 1000.
- in: query
name: pagination_key
schema:
type: string
example: agent_1ffdb9717444d0e77346838911
required: false
allowEmptyValue: true
description:
The pagination key to continue fetching the next page of agents.
Pagination key is represented by a agent id, pagination key and
version pair is exclusive (not included in the fetched page). If not
set, will start from the beginning.
- in: query
name: pagination_key_version
schema:
type: integer
example: 0
required: false
allowEmptyValue: true
description:
Specifies the version of the agent associated with the
pagination_key. When paginating, both the pagination_key and its
version must be provided to ensure consistent ordering and to fetch
the next page correctly.
responses:
"200":
description: Successfully retrieved all agents.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AgentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-chat-agents:
get:
description: List all chat agents
operationId: listChatAgents
parameters:
- in: query
name: limit
schema:
type: integer
example: 50
required: false
description:
A limit on the number of objects to be returned. Limit can range
between 1 and 1000, and the default is 1000.
- in: query
name: pagination_key
schema:
type: string
example: 16b980523634a6dc504898cda492e939
required: false
allowEmptyValue: true
description:
The pagination key to continue fetching the next page of agents.
Pagination key is represented by a agent id, pagination key and
version pair is exclusive (not included in the fetched page). If not
set, will start from the beginning.
- in: query
name: pagination_key_version
schema:
type: integer
example: 0
required: false
allowEmptyValue: true
description:
Specifies the version of the agent associated with the
pagination_key. When paginating, both the pagination_key and its
version must be provided to ensure consistent ordering and to fetch
the next page correctly.
responses:
"200":
description: Successfully retrieved all chat agents.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ChatAgentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-chat:
get:
description: List all chats
operationId: listChat
parameters:
- in: query
name: sort_order
schema:
type: string
enum:
- ascending
- descending
default: descending
description:
The chats will be sorted by `start_timestamp`, whether to return the
chats in ascending or descending order.
- in: query
name: limit
schema:
type: integer
default: 50
maximum: 1000
description:
Limit the number of chats returned. Default 50, Max 1000. To
retrieve more than 1000, use pagination_key to continue fetching the
next page.
- in: query
name: pagination_key
schema:
type: string
description:
The pagination key to continue fetching the next page of chats.
Pagination key is represented by a chat id here, and it's exclusive
(not included in the fetched chats). The last chat id from the list
chats is usually used as pagination key here. If not set, will start
from the beginning.
responses:
"200":
description: Successfully retrieved all chats.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ChatResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-conversation-flow-components:
get:
description: List shared conversation flow components with pagination
operationId: listConversationFlowComponentsV2
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/SortOrderParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Successfully listed conversation flow components
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/ConversationFlowComponentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-conversation-flow-components:
get:
description: List shared conversation flow components
operationId: listConversationFlowComponents
responses:
"200":
description: Successfully listed conversation flow components
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ConversationFlowComponentResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-conversation-flows:
get:
description: List all conversation flows that can be attached to an agent.
operationId: listConversationFlows
parameters:
- in: query
name: limit
description:
Limit the number of conversation flows returned. Default 1000, Max
1000. To retrieve more than 1000, use pagination_key to continue
fetching the next page.
schema:
type: integer
default: 1000
maximum: 1000
- in: query
name: pagination_key
description:
The pagination key to continue fetching the next page of
conversation flows. Pagination key is represented by a conversation
flow id here, and it's exclusive (not included in the fetched
conversation flows). The last conversation flow id from the list
conversation flows is usually used as pagination key here. If not
set, will start from the beginning.
schema:
type: string
- in: query
name: pagination_key_version
schema:
type: integer
description:
Specifies the version of the conversation flow associated with the
pagination_key. When paginating, both the pagination_key and its
version must be provided to ensure consistent ordering and to fetch
the next page correctly.
responses:
"200":
description: Successfully retrieved conversation flows
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ConversationFlowResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/list-knowledge-bases:
get:
description: List all knowledge bases
operationId: listKnowledgeBases
responses:
"200":
description: Successfully retrieved all knowledge bases.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/KnowledgeBaseResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-phone-numbers:
get:
description: List phone numbers with pagination
operationId: listPhoneNumbersV2
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/SortOrderParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Successfully retrieved phone numbers.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/PhoneNumberResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-phone-numbers:
get:
description: List all phone numbers
operationId: listPhoneNumbers
responses:
"200":
description: Successfully retrieved all phone numbers.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PhoneNumberResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-retell-llms:
get:
description:
List all Retell LLM Response Engines that can be attached to an agent.
operationId: listRetellLLM
parameters:
- in: query
name: limit
schema:
type: integer
example: 50
required: false
description:
A limit on the number of objects to be returned. Limit can range
between 1 and 1000, and the default is 1000.
- in: query
name: pagination_key
schema:
type: string
example: llm_1ffdb9717444d0e77346838911
required: false
allowEmptyValue: true
description:
The pagination key to continue fetching the next page of LLMs.
Pagination key is represented by a llm id, pagination key and
version pair is exclusive (not included in the fetched page). If not
set, will start from the beginning.
- in: query
name: pagination_key_version
schema:
type: integer
example: 0
required: false
allowEmptyValue: true
description:
Specifies the version of the llm associated with the pagination_key.
When paginating, both the pagination_key and its version must be
provided to ensure consistent ordering and to fetch the next page
correctly.
responses:
"200":
description: Successfully retrieved all Retell LLM Response Engines.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/RetellLLMResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/list-voices:
get:
description: List all voices available to the user
operationId: listVoices
responses:
"200":
description: Successfully retrieved all voices.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/VoiceResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/publish-agent/{agent_id}:
post:
description:
Publish the latest version of the agent and create a new draft agent
with newer version.
operationId: publishAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the agent to be published.
responses:
"200":
description: Agent successfully published
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/publish-chat-agent/{agent_id}:
post:
description:
Publish the latest version of the chat agent and create a new draft chat
agent with newer version.
operationId: publishChatAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat agent to be published.
responses:
"200":
description: Chat agent successfully published
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/update-agent/{agent_id}:
patch:
description: Update an existing agent's latest draft version
operationId: updateAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the agent to be updated.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. Default to
latest version.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentRequest"
example:
agent_name: Jarvis
responses:
"200":
description: Successfully updated an agent.
content:
application/json:
schema:
$ref: "#/components/schemas/AgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/update-chat-agent/{agent_id}:
patch:
description: Update an existing chat agent
operationId: updateChatAgent
parameters:
- in: path
name: agent_id
schema:
type: string
minLength: 1
example: 16b980523634a6dc504898cda492e939
required: true
description: Unique id of the chat agent to be updated.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. Default to
latest version.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatAgentRequest"
responses:
"200":
description: Successfully updated the chat agent.
content:
application/json:
schema:
$ref: "#/components/schemas/ChatAgentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/update-chat/{chat_id}:
patch:
description:
Update metadata and sensitive data storage settings for an existing
chat.
operationId: updateChatMetadata
parameters:
- in: path
name: chat_id
schema:
type: string
example: chat_98c1a2157aa0559144d67bb0729
required: true
description: The chat id of the chat to be updated.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the chat. Not used for processing. You can later get this
field from the chat object. Size limited to 50kB max.
data_storage_setting:
type: string
enum:
- everything
- basic_attributes_only
description:
Data storage setting for this chat. Overrides the agent's
default setting. "everything" stores all data,
"basic_attributes_only" stores only metadata. Cannot be
downgraded from more restrictive to less restrictive
settings.
example: everything
override_dynamic_variables:
type: object
additionalProperties:
type: string
example:
additional_discount: 15%
description:
Override dynamic varaibles represented as key-value pairs of
strings. Setting this will override or add the dynamic
variables set in the agent during the call. Only need to set
the delta where you want to override, no need to set the
entire dynamic variables object. Setting this to null will
remove any existing override.
nullable: true
custom_attributes:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
example:
custom_attribute_1: value1
custom_attribute_2: value2
description: Custom attributes for the chat
additionalProperties: false
example:
metadata:
customer_id: cust_123
notes: Follow-up required
data_storage_setting: everything
override_dynamic_variables:
additional_discount: 15%
responses:
"200":
description: Chat metadata updated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/ChatResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/update-conversation-flow-component/{conversation_flow_component_id}:
patch:
description: Update an existing shared conversation flow component
operationId: updateConversationFlowComponent
parameters:
- in: path
name: conversation_flow_component_id
schema:
type: string
required: true
description: ID of the component to update
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowComponent"
responses:
"200":
description: Successfully updated conversation flow component
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowComponentResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/update-conversation-flow/{conversation_flow_id}:
patch:
description: Update an existing conversation flow
operationId: updateConversationFlow
parameters:
- in: path
name: conversation_flow_id
schema:
type: string
required: true
description: Unique id of the conversation flow to be updated.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the conversation flow to update. Default to
latest version.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlow"
responses:
"200":
description: Successfully updated the conversation flow
content:
application/json:
schema:
$ref: "#/components/schemas/ConversationFlowResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/update-phone-number/{phone_number}:
patch:
description: Update agent bound to a purchased phone number
operationId: updatePhoneNumber
parameters:
- in: path
name: phone_number
schema:
type: string
minLength: 1
example: "+14157774444"
required: true
description:
E.164 format of the number (+country code, then number with no
space, no special characters), used as the unique identifier for
phone number APIs.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
inbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when receiving inbound calls. If
set to null, this number would not accept inbound call.
Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent to bind to the number. The number will
automatically use the agent when conducting outbound calls.
If set to null, this number would not be able to initiate
outbound call without agent id override. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
inbound_agent_version:
type: integer
example: 1
description:
Version of the inbound agent to bind to the number. If not
provided, will default to latest version. Deprecated. See
https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
deprecated: true
nullable: true
outbound_agent_version:
type: integer
example: 1
description:
Version of the outbound agent to bind to the number. If not
provided, will default to latest version.
nullable: true
inbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
inbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to inbound_agent_id.
nullable: true
outbound_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound agents to bind to the number with weights. If set
and non-empty, one agent will be picked randomly for each
outbound call, with probability proportional to the weight.
Total weights must add up to 1. If not set or empty,
fallback to outbound_agent_id.
nullable: true
inbound_sms_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Inbound SMS agents to bind to the number with weights. If
set and non-empty, one agent will be picked randomly for
each inbound SMS, with probability proportional to the
weight. Total weights must add up to 1. If not set or empty,
fallback to inbound_sms_agent_id.
nullable: true
outbound_sms_agents:
type: array
items:
$ref: "#/components/schemas/AgentWeight"
description:
Outbound SMS agents to bind to the number with weights. If
set and non-empty, one agent will be picked randomly for
each outbound SMS, with probability proportional to the
weight. Total weights must add up to 1. If not set or empty,
fallback to outbound_sms_agent_id.
nullable: true
nickname:
type: string
example: Frontdesk Number
description:
Nickname of the number. This is for your reference only.
nullable: true
inbound_webhook_url:
type: string
example: https://example.com/inbound-webhook
description:
If set, will send a webhook for inbound calls, where you can
to override agent id, set dynamic variables and other fields
specific to that call.
nullable: true
inbound_sms_webhook_url:
type: string
example: https://example.com/inbound-sms-webhook
description:
If set, will send a webhook for inbound SMS, where you can
override agent id, set dynamic variables and other fields
specific to that chat.
nullable: true
allowed_inbound_country_list:
type: array
items:
type: string
example: ["US", "CA", "GB"]
description:
List of ISO 3166-1 alpha-2 country codes from which inbound
calls are allowed. If not set or empty, calls from all
countries are allowed.
nullable: true
allowed_outbound_country_list:
type: array
items:
type: string
example: ["US", "CA"]
description:
List of ISO 3166-1 alpha-2 country codes to which outbound
calls are allowed. If not set or empty, calls to all
countries are allowed.
nullable: true
termination_uri:
type: string
example: someuri.pstn.twilio.com
description:
The termination uri to update for the phone number. This is
used for outbound calls.
auth_username:
type: string
example: username
description:
The username used for authentication for the SIP trunk to
update for the phone number.
auth_password:
type: string
example: "123456"
description:
The password used for authentication for the SIP trunk to
update for the phone number.
transport:
type: string
example: "TCP"
description:
Outbound transport protocol to update for the phone number.
Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
nullable: true
fallback_number:
type: string
example: "+14155551234"
description:
Enterprise only. Phone number to transfer inbound calls to
when organization is in outage mode. Can be either a Retell
phone number or an external number. Set to null to remove.
Cannot be the same as this phone number, and cannot be a
number that already has its own fallback configured
(prevents nested forwarding).
nullable: true
example:
inbound_agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
outbound_agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
nickname: Frontdesk Number
responses:
"200":
description: Successfully updated an phone number object.
content:
application/json:
schema:
$ref: "#/components/schemas/PhoneNumberResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/update-retell-llm/{llm_id}:
patch:
description: Update an existing Retell LLM Response Engine
operationId: updateRetellLLM
parameters:
- in: path
name: llm_id
schema:
type: string
example: 16b980523634a6dc504898cda492e939
required: true
description:
Unique id of the Retell LLM Response Engine to be updated.
- in: query
name: version
schema:
type: integer
example: 1
required: false
description:
Optional version of the API to use for this request. Default to
latest version.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RetellLlmRequest"
example:
begin_message:
Hey I am a virtual assistant calling from Retell Hospital.
responses:
"200":
description: Successfully updated an Retell LLM Response Engine.
content:
application/json:
schema:
$ref: "#/components/schemas/RetellLLMResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/create-phone-call:
post:
description: Create a new outbound phone call
operationId: createPhoneCall
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from_number
- to_number
properties:
from_number:
type: string
minLength: 1
example: "+14157774444"
description:
The number you own in E.164 format. Must be a number
purchased from Retell or imported to Retell.
to_number:
type: string
minLength: 1
example: "+12137774445"
description:
The number you want to call, in E.164 format. If using a
number purchased from Retell, only US numbers are supported
as destination.
override_agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
For this particular call, override the agent used with this
agent id. This does not bind the agent to this number, this
is for one time override.
override_agent_version:
type: integer
example: 1
description:
For this particular call, override the agent version used
with this version. This does not bind the agent version to
this number, this is for one time override.
agent_override:
$ref: "#/components/schemas/AgentOverrideRequest"
description:
For this particular call, override agent configuration with
these settings. This allows you to customize agent behavior
for individual calls without modifying the base agent.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the call. Not used for processing. You can later get this
field from the call object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string
that injects into your Response Engine prompt and tool
description. Only applicable for Response Engine.
custom_sip_headers:
type: object
additionalProperties:
type: string
example:
X-Custom-Header: Custom Value
description: Add optional custom SIP headers to the call.
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: true
responses:
"201":
description: Successfully made an outbound call.
content:
application/json:
schema:
$ref: "#/components/schemas/V2PhoneCallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/create-web-call:
post:
description: Create a new web call
operationId: createWebCall
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
properties:
agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description:
Unique id of agent used for the call. Your agent would
contain the LLM Websocket url used for this call.
agent_version:
type: integer
example: 1
description: The version of the agent to use for the call.
agent_override:
$ref: "#/components/schemas/AgentOverrideRequest"
description:
For this particular call, override agent configuration with
these settings. This allows you to customize agent behavior
for individual calls without modifying the base agent.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the call. Not used for processing. You can later get this
field from the call object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string
that injects into your Response Engine prompt and tool
description. Only applicable for Response Engine.
current_node_id:
type: string
example: collect_info
description:
Start the call at this conversation flow node (stage). Must
be a valid node id in the agent's conversation flow. Only
applicable when the agent uses conversation flow as the
response engine. Ignored for retell-llm agents.
nullable: true
current_state:
type: string
example: information_collection
description:
Start the conversation in this state (stage). Must be a
valid state name in the agent's Retell LLM. Only applicable
when the agent uses Retell LLM with states. Ignored for
conversation-flow agents.
nullable: true
responses:
"201":
description: Successfully created a web call.
content:
application/json:
schema:
$ref: "#/components/schemas/V2WebCallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/delete-call/{call_id}:
delete:
description: Delete a specific call and its associated data
operationId: deleteCall
parameters:
- in: path
name: call_id
schema:
type: string
example: 119c3f8e47135a29e65947eeb34cf12d
required: true
description: The call id to delete.
responses:
"204":
description: Call successfully deleted. No content returned.
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/get-call/{call_id}:
get:
description: Retrieve details of a specific call
operationId: getCall
parameters:
- in: path
name: call_id
schema:
type: string
example: 119c3f8e47135a29e65947eeb34cf12d
required: true
description: The call id to retrieve call history for.
responses:
"200":
description: Successfully retrieved a call.
content:
application/json:
schema:
$ref: "#/components/schemas/V2CallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-calls:
post:
description: Retrieve call details
operationId: listCalls
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
filter_criteria:
type: object
description: Filter criteria for the calls to retrieve.
example:
call_id:
- call_5a82f0a43ea0977566b1104fcfc
agent_id:
- agent_oBeDLoLOeuAbiuaMFXRtDOLriT12345
call_status:
- ended
call_type:
- phone_call
direction:
- inbound
user_sentiment:
- Positive
call_successful:
- true
start_timestamp:
upper_threshold: 1738475421000
lower_threshold: 1738475411000
metadata.customer_id:
- "cust_123"
dynamic_variables.user_name:
- "John"
properties:
call_id:
type: array
items:
type: string
minLength: 1
description: Only retrieve calls with specific call id(s).
agent_id:
type: array
items:
type: string
minLength: 1
description:
Only retrieve calls that are made with specific
agent(s).
version:
type: array
items:
type: integer
description: The version of the agent to use for the call.
call_status:
type: array
items:
type: string
enum:
- not_connected
- ongoing
- ended
- error
description:
Only retrieve calls with specific call status(es).
in_voicemail:
type: array
items:
type: boolean
description:
Only retrieve calls that are in voicemail or not in
voicemail.
disconnection_reason:
type: array
items:
$ref: "#/components/schemas/DisconnectionReason"
description:
Only retrieve calls with specific disconnection
reason(s).
from_number:
type: array
items:
type: string
minLength: 1
description:
Only retrieve calls with specific from number(s).
to_number:
type: array
items:
type: string
minLength: 1
description:
Only retrieve calls with specific to number(s).
batch_call_id:
type: array
items:
type: string
description:
Only retrieve calls with specific batch call id(s).
call_type:
type: array
items:
type: string
enum:
- web_call
- phone_call
description:
Only retrieve calls with specific call type(s).
direction:
type: array
items:
type: string
enum:
- inbound
- outbound
description:
Only retrieve calls with specific direction(s).
user_sentiment:
type: array
items:
type: string
enum:
- Negative
- Positive
- Neutral
- Unknown
description:
Only retrieve calls with specific user sentiment(s).
call_successful:
type: array
items:
type: boolean
description:
Only retrieve calls with specific call successful(s).
start_timestamp:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description:
Only retrieve calls with specific range of start
timestamp(s).
end_timestamp:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description:
Only retrieve calls with specific range of end
timestamp(s).
duration_ms:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
description:
Only retrieve calls with specific range of duration(s).
e2e_latency_p50:
type: object
properties:
upper_threshold:
type: integer
lower_threshold:
type: integer
metadata:
type: object
description: |
Filter by metadata fields using dot notation (e.g., `metadata.customer_id`).
Values are matched exactly as strings.
additionalProperties:
type: array
items:
type: string
example:
metadata.customer_id:
- "cust_123"
dynamic_variables:
type: object
description: |
Filter by dynamic variables using dot notation (e.g., `dynamic_variables.name`).
Values are matched exactly as strings.
additionalProperties:
type: array
items:
type: string
example:
dynamic_variables.user_name:
- "John"
sort_order:
type: string
enum:
- ascending
- descending
default: descending
description:
The calls will be sorted by `start_timestamp`, whether to
return the calls in ascending or descending order.
limit:
type: integer
default: 50
description:
Limit the number of calls returned. Default 50, Max 1000. To
retrieve more than 1000, use pagination_key to continue
fetching the next page.
pagination_key:
type: string
description:
The pagination key to continue fetching the next page of
calls. Pagination key is represented by a call id here, and
it's exclusive (not included in the fetched calls). The last
call id from the list calls is usually used as pagination
key here. If not set, will start from the beginning.
responses:
"200":
description: Successfully retrieved calls.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/V2CallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/list-export-requests:
get:
description: List export requests with pagination
operationId: listExportRequestsV2
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/SortOrderParam"
- $ref: "#/components/parameters/PaginationKeyParam"
responses:
"200":
description: Export requests retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedResponseBase"
- type: object
properties:
items:
type: array
items:
type: object
properties:
export_request_id:
type: string
channel:
type: string
enum:
- call
- chat
status:
type: string
enum:
- created
- processing
- completed
- error
url:
type: string
created_timestamp:
type: integer
timezone:
type: string
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/register-phone-call:
post:
description: Register a new phone call for custom telephony
operationId: registerPhoneCall
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
properties:
agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
description: The agent to use for the call.
agent_version:
type: integer
example: 1
description: The version of the agent to use for the call.
agent_override:
$ref: "#/components/schemas/AgentOverrideRequest"
description:
For this particular call, override agent configuration with
these settings. This allows you to customize agent behavior
for individual calls without modifying the base agent.
from_number:
type: string
minLength: 1
example: "+14157774444"
description:
The number you own in E.164 format. Stored for tracking
purpose.
to_number:
type: string
minLength: 1
example: "+12137774445"
description:
The number you want to call, in E.164 format. Stored for
tracking purpose.
direction:
type: string
enum:
- inbound
- outbound
example: inbound
description:
Direction of the phone call. Stored for tracking purpose.
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the call. Not used for processing. You can later get this
field from the call object.
retell_llm_dynamic_variables:
type: object
additionalProperties: {}
example:
customer_name: John Doe
description:
Add optional dynamic variables in key value pairs of string
that injects into your Response Engine prompt and tool
description. Only applicable for Response Engine.
responses:
"201":
description: Successfully registered a phone call.
content:
application/json:
schema:
$ref: "#/components/schemas/V2PhoneCallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"402":
$ref: "#/components/responses/PaymentRequired"
"422":
$ref: "#/components/responses/UnprocessableContent"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/v2/update-call/{call_id}:
patch:
description:
Update metadata and sensitive data storage settings for an existing
call.
operationId: updateCallMetadata
parameters:
- in: path
name: call_id
schema:
type: string
example: call_a4441234567890777c4a4a123e6
required: true
description: The call id of the call to be updated.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
description:
An arbitrary object for storage purpose only. You can put
anything here like your internal customer id associated with
the call. Not used for processing. You can later get this
field from the call object. Size limited to 50kB max.
example:
customer_id: cust_123
notes: Follow-up required
data_storage_setting:
type: string
enum:
- everything
- everything_except_pii
- basic_attributes_only
description:
Data storage setting for this call. Overrides the agent's
default setting. "everything" stores all data,
"everything_except_pii" excludes PII when possible,
"basic_attributes_only" stores only metadata. Cannot be
downgraded from more restrictive to less restrictive
settings.
example: everything_except_pii
override_dynamic_variables:
type: object
additionalProperties:
type: string
example:
additional_discount: 15%
description:
Override dynamic varaibles represented as key-value pairs of
strings. Setting this will override or add the dynamic
variables set in the agent during the call. Only need to set
the delta where you want to override, no need to set the
entire dynamic variables object. Setting this to null will
remove any existing override.
nullable: true
custom_attributes:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
example:
custom_attribute_1: value1
custom_attribute_2: value2
description: Custom attributes for the call
additionalProperties: false
example:
metadata:
customer_id: cust_123
notes: Follow-up required
data_storage_setting: everything_except_pii
responses:
"200":
description: Call metadata updated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/V2CallResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"422":
$ref: "#/components/responses/UnprocessableContent"
"500":
$ref: "#/components/responses/InternalServerError"