REST API at https://api.retellai.com for managing agents, conversation flows, calls (phone and chat), voices, knowledge bases, retell LLM, batch calls, and call analyses. Auth is bearer token. OpenAPI spec is published at https://docs.retellai.com/openapi.yaml.
openapi: 3.0.3
info:
title: Retell SDK
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: [email protected]
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.
Conflict:
description: Conflict
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Resource update conflict.
PreconditionFailed:
description: Precondition Failed
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Precondition failed for conditional update.
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
AsrProvider:
type: string
enum:
- azure
- deepgram
- soniox
description: ASR provider name.
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:
$ref: '#/components/schemas/AgentVersionReference'
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.
AgentVersionReference:
oneOf:
- type: integer
minimum: 0
example: 1
- type: string
minLength: 1
maxLength: 20
pattern: ^[a-z0-9_-]+$
example: prod
description: >-
Agent version reference. Supports a numeric version (for example 3) or a
tag/environment name (for example "prod"). When a tag is provided,
resolution uses that exact tag assignment (including its dynamic
variables). If the tag exists but is currently unassigned, it resolves
to latest. When a numeric version (or latest) is provided, resolution
applies dynamic variables from the preferred tag for that resolved
version (most recently assigned), if any.
CreateAgentVersionRequest:
type: object
additionalProperties: false
required:
- base_version
properties:
base_version:
type: integer
minimum: 0
example: 12
description: Existing version used as the base when creating a new draft.
PublishAgentVersionRequest:
type: object
required:
- version
properties:
version:
type: integer
minimum: 0
example: 15
version_description:
type: string
example: Hotfix for transfer timeout
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
- s2-pro
- 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:
oneOf:
- $ref: '#/components/schemas/LanguageLegacy'
- type: array
items:
$ref: '#/components/schemas/Language'
description: >-
Specifies what language(s) the agent will operate in. Accepts either
a single scalar locale (e.g. `en-US`), the legacy scalar value
`multi` for multilingual support, or an array of concrete locale
codes for explicit multi-locale selection (e.g.
`["en-US","es-ES"]`). The array form must contain concrete locale
codes only — the `multi` value is valid only as the scalar legacy
form and must not appear inside an array. Single-element arrays are
normalized to the equivalent scalar on output. If unset, defaults to
`en-US`.
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: str
# --- truncated at 32 KB (421 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-openapi.yml