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/AnalysisData" 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. 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" 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. 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/AnalysisData" 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. 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 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 ConversationFlowNode: oneOf: - $ref: "#/components/schemas/ConversationNode" - $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 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 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 conversation node. nullable: true tools: type: array items: $ref: "#/components/schemas/Tool" description: The tools owned by this conversation 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. 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. 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 # Internal API (admin / internal users only) 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 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. 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. 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. 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 form data with string values example: favorite_color: blue preferred_contact: email 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"