openapi: 3.0.3 info: title: Retell SDK version: 3.0.0 x-retell-spec-revision: 2026-08-01-ad84c11 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. Conflict: description: Conflict content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Resource update conflict. PreconditionFailed: description: Precondition Failed content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Precondition failed for conditional update. parameters: LimitParam: in: query name: limit schema: type: integer default: 50 maximum: 1000 description: Maximum number of items to return. SortOrderParam: in: query name: sort_order schema: type: string enum: - ascending - descending default: descending description: Sort order for results. PaginationKeyParam: in: query name: pagination_key schema: type: string description: Pagination key for fetching the next page. SearchParam: in: query name: search schema: type: string description: Case-insensitive substring match against the item's title. 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 - chat_count - chat_success_rate - chat_negative_sentiment_rate - total_chat_cost AsrProvider: type: string enum: - azure - deepgram - soniox - assemblyai description: ASR provider name. AsrProviderModeRouting: type: object description: >- Routing for one mode (fast or accurate). `provider` is the dominant provider (what most calls hit). When traffic is split across a chance gate, `split` is present and lists every provider with its explicit traffic `fraction` (dominant first); otherwise all calls hit `provider`. required: - provider - endpointing_ms properties: provider: $ref: '#/components/schemas/AsrProvider' endpointing_ms: type: integer split: type: array description: >- Present only when traffic is split across a chance gate. Each entry is a provider and the `fraction` (0–1) of calls routed to it, stably bucketed by call id; fractions sum to 1. Sorted by `fraction` descending, so the first entry matches the top-level `provider`. items: type: object required: - provider - endpointing_ms - fraction properties: provider: $ref: '#/components/schemas/AsrProvider' endpointing_ms: type: integer fraction: type: number 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. agent_tag: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Agent environment tag(s) to filter on (e.g. "prod", "staging"). 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 description: Analysis of how natural the agent's speech sounds per utterance. required: - details - natural_utterance_count - total_utterance_count properties: details: type: array items: $ref: '#/components/schemas/UtteranceNaturalnessIssues' description: Per-utterance naturalness issue details. natural_utterance_count: type: number description: Number of utterances judged to sound natural. total_utterance_count: type: number AgentWeight: type: object required: - agent_id - weight properties: agent_id: type: string minLength: 1 example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD agent_version: $ref: '#/components/schemas/AgentVersionReference' weight: type: number example: 0.5 minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The weight of the agent. When used in a list of agents, the total weights must add up to 1. AgentVersionReference: oneOf: - type: string minLength: 1 maxLength: 20 pattern: >- ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ example: latest_published - type: integer minimum: 0 example: 1 description: >- Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any. CreateAgentVersionRequest: type: object additionalProperties: false required: - base_version properties: base_version: type: integer minimum: 0 example: 12 description: Existing version used as the base when creating a new draft. PublishAgentVersionRequest: type: object required: - version properties: version: type: integer minimum: 0 example: 15 version_description: type: string example: Hotfix for transfer timeout version_title: type: string example: Hotfix description: Optional title of the agent version. Used for your own reference. AgentRootTagState: type: object properties: version: type: integer minimum: 0 example: 15 dynamic_variables: type: object additionalProperties: type: string 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 version_title: type: string example: Production hotfix description: Optional title of the agent version. Used for your own reference. 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_flash_v2 - eleven_flash_v2_5 - eleven_multilingual_v2 - eleven_v3 - sonic-3 - sonic-3-latest - sonic-3.5 - tts-1 - gpt-4o-mini-tts - speech-02-turbo - speech-2.8-turbo - s1 - s2-pro - s2.1-pro - null description: >- Select the voice model used for the selected voice. Each provider has a set of available voice models. Set to null to remove voice model selection, and default ones will apply. Check out dashboard for more details of each voice model. nullable: true fallback_voice_ids: type: array items: type: string example: - cartesia-Cimo - minimax-Cimo description: >- When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent. nullable: true voice_temperature: type: number example: 1 description: >- Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Check the dashboard to see what provider supports this feature. If unset, default value 1 will apply. voice_speed: type: number minimum: 0.5 maximum: 2 example: 1 description: >- Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply. enable_dynamic_voice_speed: type: boolean example: true description: >- If set to true, will enable dynamic voice speed adjustment based on the user's speech rate and conversation context. If unset, default value false will apply. enable_dynamic_responsiveness: type: boolean example: true description: >- If set to true, the agent will dynamically adjust how quickly it responds based on the user's speech rate and past turn-taking behavior in the call. If unset, default value false will apply. volume: type: number example: 1 description: >- If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply. voice_emotion: type: string nullable: true enum: - calm - sympathetic - happy - sad - angry - fearful - surprised - null example: calm description: > Controls the emotional tone of the agent's voice. Currently supported for Cartesia and Minimax TTS providers. If unset, no emotion will be used. enable_expressive_mode: type: boolean example: true description: >- Master toggle for expressive mode. When true, the agent may add expressive voice tags to the audio it generates. Only applicable for platform voices. If unset, defaults to false. expressive_emotion_tags: type: array uniqueItems: true items: type: string enum: - empathetic - excited - happy - curious - surprised - sigh - clear throat - pause - long pause - emphasis example: - empathetic - excited - sigh - clear throat - emphasis description: >- The expressive voice tags Retell pre-teaches the model to use when enable_expressive_mode is true. Custom tags defined in the system prompt are still allowed. If empty, the agent follows general expressive guidance without a fixed tag set. expressive_mode_prompt: type: string nullable: true example: Use [sigh] for thoughtful pauses and [excited] for good news. description: >- Custom expressive voice guidance to use instead of the default Retell expressive prompt when enable_expressive_mode is true. If omitted or blank, the default expressive prompt will be used. responsiveness: type: number minimum: 0 maximum: 1 example: 1 description: >- Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply. interruption_sensitivity: type: number minimum: 0 maximum: 1 example: 1 description: >- Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted. enable_backchannel: type: boolean example: true description: >- Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel. backchannel_frequency: type: number example: 0.9 description: >- Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply. backchannel_words: type: array items: type: string example: - yeah - uh-huh description: >- Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out [backchannel default words](/agent/interaction-configuration#backchannel) for more details. Note that certain voices do not work too well with certain words, so it's recommended to experiment before adding any words. nullable: true reminder_trigger_ms: type: number example: 10000 description: >- If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply. reminder_max_count: type: integer example: 2 description: >- If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding. ambient_sound: type: string enum: - coffee-shop - convention-hall - summer-outdoor - mountain-outdoor - static-noise - call-center - null description: > If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options: - `coffee-shop`: Coffee shop ambience with people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/coffee-shop.wav) - `convention-hall`: Convention hall ambience, with some echo and people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/convention-hall.wav) - `summer-outdoor`: Summer outdoor ambience with cicada chirping. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/summer-outdoor.wav) - `mountain-outdoor`: Mountain outdoor ambience with birds singing. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/mountain-outdoor.wav) - `static-noise`: Constant static noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/static-noise.wav) - `call-center`: Call center work noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/call-center.wav) Set to `null` to remove ambient sound from this agent. nullable: true ambient_sound_volume: type: number example: 1 description: >- If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply. language: oneOf: - $ref: '#/components/schemas/LanguageLegacy' - type: array items: $ref: '#/components/schemas/Language' description: >- Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`. webhook_url: type: string example: https://webhook-url-here description: >- The webhook for agent to listen to call events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent. nullable: true webhook_events: type: array items: type: string enum: - call_started - call_ended - call_analyzed - transcript_updated - transfer_started - transfer_bridged - transfer_cancelled - transfer_ended description: >- Which webhook events this agent should receive. If not set, defaults to call_started, call_ended, call_analyzed. nullable: true webhook_timeout_ms: type: integer example: 10000 description: >- The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. boosted_keywords: type: array items: type: string example: - retell - kroger description: >- Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc. Entries may reference dynamic variables with `{{variable}}` syntax. 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: ˈæktʃuəli 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 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_option: type: object properties: action: $ref: '#/components/schemas/VoicemailAction' detection_prompt: type: string maxLength: 2000 nullable: true description: >- Optionally describe what should be treated as voicemail. Leave as null to use the default definition. 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' detection_prompt: type: string maxLength: 2000 nullable: true description: >- Optionally describe what should be treated as an IVR. Leave as null to use the default definition. 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 call_screening_option: $ref: '#/components/schemas/CallScreeningOption' post_call_analysis_data: type: array items: $ref: '#/components/schemas/PostCallAnalysisData' description: >- Post call analysis data to extract from the call. This data will augment the pre-defined variables extracted in the call analysis. This will be available after the call ends. nullable: true post_call_analysis_model: $ref: '#/components/schemas/NullableLLMModel' example: gpt-4.1-mini description: The model to use for post call analysis. Default to gpt-4.1. 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: allOf: - $ref: '#/components/schemas/AsrProvider' description: The STT provider to use. endpointing_ms: type: integer description: >- Endpointing timeout in milliseconds. Minimum is 100 for Azure, 10 for Deepgram, 500 for Soniox, 100 for AssemblyAI. 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. allow_dtmf_interruption: type: boolean example: false description: >- If set to true, DTMF input will interrupt the agent even when interruption_sensitivity is 0. Can be overridden per conversation or subagent node. Default to false. user_dtmf_options: type: object properties: digit_limit: type: number description: >- The maximum number of digits allowed in the user's DTMF (Dual-Tone Multi-Frequency) input per turn. Once this limit is reached, the input is considered complete and a response will be generated immediately. nullable: true minimum: 1 maximum: 50 termination_key: type: string nullable: true description: >- A single key that signals the end of DTMF input. Acceptable values include any digit (0-9), the pound/hash symbol (#), or the asterisk (*). example: '#' timeout_ms: type: integer description: >- The time (in milliseconds) to wait for user DTMF input before timing out. The timer resets with each digit received. minimum: 1000 maximum: 15000 nullable: true denoising_mode: type: string enum: - no-denoise - noise-cancellation - noise-and-background-speech-cancellation example: noise-cancellation description: >- If set, determines what denoising mode to use. Use "no-denoise" to bypass all audio denoising. Default to noise-cancellation. pii_config: $ref: '#/components/schemas/PIIConfig' description: Configuration for PII scrubbing from transcripts and recordings. guardrail_config: $ref: '#/components/schemas/GuardrailConfig' description: >- Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input. handbook_config: $ref: '#/components/schemas/VoiceHandbookConfig' description: >- Toggle behavior presets on/off to influence agent response style and behaviors. timezone: type: string description: >- IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. example: America/New_York nullable: true 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. base_version: type: integer nullable: true example: 12 description: Version that this draft was based on. Null for initial versions. assigned_tags: type: array items: type: string description: >- Tags assigned to this agent version. Preferred tag is listed first. 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. AgentListFilter: type: object description: Filters for listing agents. All provided filters are connected with AND. properties: channel: allOf: - $ref: '#/components/schemas/StringFilter' - description: 'Filter by agent channel. Use `op: eq`.' properties: op: enum: - eq value: enum: - voice - chat query: type: string description: >- Case-insensitive substring search over agent name, plus substring search over agent id. AgentListItemResponse: type: object required: - agent_id - agent_name - channel - user_modified_timestamp - tags properties: agent_id: type: string example: agent_1ffdb9717444d0e77346838911 description: Unique id of agent. agent_name: type: string example: Jarvis description: The name of the agent. Only used for your own reference. channel: type: string enum: - voice - chat example: voice user_modified_timestamp: type: integer format: int64 example: 1703413636133 description: >- User modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available. tags: type: object description: Authoritative root tags for this agent, keyed by tag name. additionalProperties: $ref: '#/components/schemas/AgentRootTagState' 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: $ref: '#/components/schemas/AgentVersionReference' 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: $ref: '#/components/schemas/AgentVersionReference' description: >- The version of the agent to swap to. If not specified, will use the latest version. speak_during_execution: type: boolean execution_message_description: type: string description: The message for the agent to speak when executing agent swap. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". post_call_analysis_setting: $ref: '#/components/schemas/PostCallAnalysisSetting' description: Post call analysis setting for the agent swap. webhook_setting: $ref: '#/components/schemas/AgentSwapWebhookSetting' description: Webhook setting for the agent swap, defaults to only source. keep_current_voice: type: boolean description: >- If true, keep the current voice when swapping agents. Defaults to false. keep_current_language: type: boolean description: >- If true, keep the current language when swapping agents. Defaults to false. required: - type - name - agent_id - post_call_analysis_setting AgentSwapWebhookSetting: type: string enum: - both_agents - only_destination_agent - only_source_agent AnalysisData: oneOf: - $ref: '#/components/schemas/StringAnalysisData' - $ref: '#/components/schemas/EnumAnalysisData' - $ref: '#/components/schemas/BooleanAnalysisData' - $ref: '#/components/schemas/NumberAnalysisData' PostCallAnalysisData: oneOf: - $ref: '#/components/schemas/AnalysisData' - $ref: '#/components/schemas/CallPresetAnalysisData' description: >- Post-call analysis item (custom data or voice preset). Use for voice agent post_call_analysis_data; validates only call presets (call_summary, call_successful, user_sentiment). PostChatAnalysisData: oneOf: - $ref: '#/components/schemas/AnalysisData' - $ref: '#/components/schemas/ChatPresetAnalysisData' description: >- Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment). AverageMetric: type: object required: - time_averages - overall_average properties: time_averages: type: array description: >- Contains one average per entry in timepoints, in the same order. null indicates no qualifying observations for that metric. items: type: number nullable: true overall_average: type: number nullable: true description: Weighted average across all time buckets. numerator: type: number description: Aggregate numerator used to calculate overall_average. denominator: type: number description: Aggregate denominator used to calculate overall_average. 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 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: $ref: '#/components/schemas/AgentVersionReference' 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: type: string example: customer_name: John Doe description: >- Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine. metadata: type: object description: >- An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object. custom_sip_headers: type: object additionalProperties: type: string example: X-Custom-Header: Custom Value description: Add optional custom SIP headers to the call. BookAppointmentCalTool: type: object properties: type: type: string enum: - book_appointment_cal name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). description: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. cal_api_key: type: string description: >- Cal.com Api key that have access to the cal.com event you want to book appointment. event_type_id: oneOf: - type: number - type: string description: >- Cal.com event type id number for the cal.com event you want to book appointment. Can be a number or a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. timezone: type: string description: >- Timezone to be used when booking appointment, must be in [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Can also be a dynamic variable in the format `{{variable_name}}` that will be resolved at runtime. If not specified, will check if user specified timezone in call, and if not, will use the timezone of the Retell servers. required: - type - name - cal_api_key - event_type_id BooleanAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - boolean description: Type of the variable to extract. example: boolean name: type: string description: Name of the variable. example: is_converted minLength: 1 description: type: string description: Description of the variable. example: Whether the customer converted. required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. BranchNode: allOf: - $ref: '#/components/schemas/NodeBase' - type: object required: - type - else_edge properties: type: type: string enum: - branch description: Type of the node edges: type: array items: $ref: '#/components/schemas/NodeEdge' else_edge: $ref: '#/components/schemas/ElseEdge' finetune_transition_examples: type: array items: $ref: '#/components/schemas/NodeFinetuneTransitionExample' BreakdownMetric: type: object required: - overall_breakdown - time_breakdown properties: overall_breakdown: type: array description: Aggregate counts for each category across all time buckets. items: $ref: '#/components/schemas/Breakdown' time_breakdown: type: array description: >- Each element contains the category breakdown for the corresponding entry in timepoints, in the same order. items: type: array items: $ref: '#/components/schemas/Breakdown' Breakdown: type: object required: - metric_name - metric_value properties: metric_name: type: string description: Name of the category. metric_value: type: number description: Number of occurrences in the category. 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 description: QA result for a single call within a cohort. required: - call_qa_id - call_id - cohort_id - cohort_version - score - passed - failed_metrics - passed_metrics - questions - question_resolutions - call_start_time_ms - analyzed - calibrated properties: call_qa_id: type: string call_id: type: string cohort_id: type: string cohort_version: type: number description: Cohort version this QA was created against. score: type: number description: Sum of score weights for passed metrics, ranging from 0 to 100. passed: type: boolean description: Whether the call met the cohort's success criteria. interruptions: $ref: '#/components/schemas/InterruptionAnalysis' description: Analysis of instances where the agent interrupted the user. user_sentiments: $ref: '#/components/schemas/SentimentAnalysis' description: Per-utterance user sentiment analysis. agent_sentiments: $ref: '#/components/schemas/SentimentAnalysis' description: Per-utterance agent sentiment analysis. agent_naturalness_analysis: $ref: '#/components/schemas/AgentNaturalnessAnalysis' description: Analysis of how natural the agent's speech sounds. transcription_error_analysis: $ref: '#/components/schemas/TranscriptionErrorAnalysis' description: >- Mistranscribed important entities and overall word error rate for the call. rag_analysis: $ref: '#/components/schemas/RAGAnalysis' description: Knowledge base retrieval accuracy and recall analysis. custom_tool_analysis: $ref: '#/components/schemas/ToolCallMetricAnalysis' description: Latency and success outcomes for custom tool calls. tool_call_analysis: $ref: '#/components/schemas/ToolCallAccuracyAnalysis' description: Analysis of whether tool calls were made accurately. node_transition_analysis: $ref: '#/components/schemas/NodeTransitionAnalysis' llm_hallucination_analysis: $ref: '#/components/schemas/HallucinationAnalysis' description: Analysis of agent hallucinations. transfer_call_analysis: $ref: '#/components/schemas/ToolCallMetricAnalysis' description: Latency and success outcomes for transfer calls. failure_reason: type: string description: Summary of why the call did not pass the cohort's success criteria. failed_metrics: type: array items: $ref: '#/components/schemas/MetricResult' passed_metrics: type: array items: $ref: '#/components/schemas/MetricResult' questions: type: array items: type: string description: Questions asked by the user during the call. question_resolutions: type: array items: type: boolean description: Whether each corresponding question in `questions` was resolved. notes: type: string description: Notes added by the user during calibration. question_clusters: type: array items: type: string description: Cluster IDs the call's questions were grouped into. call_start_time_ms: type: number description: Start time of the call (epoch milliseconds). analyzed: type: boolean description: Whether QA analysis has completed for this call. calibrated: type: boolean description: >- True if a human reviewed or overrode the automatic scoring; false until a review occurs. 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 description: Condensed QA summary returned when listing a cohort's calls. required: - call_qa_id - call_id - cohort_id - call_start_time_ms - score - passed - calibrated properties: call_qa_id: type: string call_id: type: string cohort_id: type: string call_start_time_ms: type: number description: Call start time in epoch milliseconds. score: type: number description: Weighted QA score from 0 to 100. passed: type: boolean description: Whether the call met the cohort's success criteria. interruption_count: type: number nullable: true description: Number of times the agent interrupted the user. llm_hallucination_rate: type: number nullable: true description: Fraction of evaluated agent utterances with hallucinations. kb_recall: type: number nullable: true description: Fraction of evaluated retrievals with full chunk recall. transition_accuracy: type: number nullable: true description: Fraction of evaluated node transitions that were correct. user_positive_sentiment_rate: type: number nullable: true description: Fraction of evaluated user utterances with positive sentiment. user_negative_sentiment_rate: type: number nullable: true description: Fraction of evaluated user utterances with negative sentiment. wer: type: number nullable: true description: Word error rate of the call transcript. tool_call_accuracy: type: number nullable: true description: Fraction of evaluated tool-call utterances that were accurate. natural_tonality_rate: type: number nullable: true description: Fraction of evaluated agent utterances judged natural. calibrated: type: boolean description: Whether the QA was reviewed by a human. PreviewCallQA: description: Condensed call QA summary with the call duration. allOf: - $ref: '#/components/schemas/ChCallQA' - type: object required: - duration_ms properties: duration_ms: type: number description: Call duration in milliseconds. 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 version_title: type: string example: Production hotfix description: >- Optional title of the chat agent version. 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: oneOf: - $ref: '#/components/schemas/LanguageLegacy' - type: array items: $ref: '#/components/schemas/Language' description: >- Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`. webhook_url: type: string example: https://webhook-url-here description: >- The webhook for agent to listen to 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 - transcript_updated description: >- Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed. nullable: true webhook_timeout_ms: type: integer example: 10000 description: >- The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. data_storage_setting: type: string enum: - everything - everything_except_pii - basic_attributes_only example: everything description: >- Controls what data is stored for this agent. "everything" stores all data including transcripts and recordings. "everything_except_pii" stores data but excludes PII when possible based on PII configuration. "basic_attributes_only" stores only basic metadata. If not set, defaults to "everything". nullable: true data_storage_retention_days: type: integer minimum: 1 maximum: 730 example: 30 nullable: true description: >- Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion). opt_in_signed_url: type: boolean example: true description: >- Whether this agent opts in to signed url for public log. If not set, default value of false will apply. signed_url_expiration_ms: type: integer example: 86400000 description: >- The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply. nullable: true post_chat_analysis_data: type: array items: $ref: '#/components/schemas/PostChatAnalysisData' description: >- Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends. nullable: true post_chat_analysis_model: $ref: '#/components/schemas/NullableLLMModel' example: gpt-4.1-mini description: The model to use for post chat analysis. Default to gpt-4.1. pii_config: $ref: '#/components/schemas/PIIConfig' description: Configuration for PII scrubbing from transcripts and recordings. guardrail_config: $ref: '#/components/schemas/GuardrailConfig' description: >- Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input. handbook_config: $ref: '#/components/schemas/ChatHandbookConfig' description: >- Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents. timezone: type: string description: >- IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. example: America/New_York nullable: true 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. base_version: type: integer nullable: true example: 12 description: Version that this draft was based on. Null for initial versions. assigned_tags: type: array items: type: string description: >- Tags assigned to this chat agent version. Preferred tag is listed first. 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: type: string 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: type: string 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' V3ChatResponse: allOf: - $ref: '#/components/schemas/ChatResponse' - type: object description: V3 list chats response. Transcript fields are intentionally omitted. not: anyOf: - required: - transcript - required: - message_with_tool_calls - required: - scrubbed_message_with_tool_calls - required: - pre_session_message_with_tool_calls - required: - scrubbed_pre_session_message_with_tool_calls - required: - post_session_message_with_tool_calls - required: - scrubbed_post_session_message_with_tool_calls 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 description: >- Aggregated QA metrics across all scored calls in a cohort, bucketed into a time series. required: - total_calls - calls_analysed - timepoints - group_by - avg_score - call_resolution_rate - top_questions - 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: total_calls: type: number description: >- Total calls sampled into the cohort over the time series, including those not yet analyzed. calls_analysed: type: number description: Number of calls that have completed QA analysis. timepoints: type: array items: type: number description: >- Start timestamp of each time bucket in the series, in the requested timezone. group_by: type: string enum: - hour - day - week - month description: Granularity used to bucket the time series. avg_score: $ref: '#/components/schemas/AverageMetric' description: Average QA score over the time series. call_resolution_rate: $ref: '#/components/schemas/AverageMetric' description: >- Pass rate over the time series and in aggregate — the fraction of analyzed calls that met the cohort's success criteria. top_questions: type: array description: Most common question clusters and their resolution counts. 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 latency: $ref: '#/components/schemas/AverageMetric' description: End-to-end agent response latency in milliseconds. llm_hallucination_analysis: $ref: '#/components/schemas/AverageMetric' description: Agent hallucination rate. rag_analysis: $ref: '#/components/schemas/AverageMetric' description: Knowledge base retrieval recall rate. user_sentiment: $ref: '#/components/schemas/BreakdownMetric' description: Breakdown of user sentiment (positive/neutral/negative). agent_sentiment: $ref: '#/components/schemas/BreakdownMetric' description: Breakdown of agent sentiment (positive/neutral/negative). transfer_success_rate: $ref: '#/components/schemas/AverageMetric' description: Success rate of transfer calls. transfer_wait_time: $ref: '#/components/schemas/AverageMetric' description: Average wait time before a transfer connects, in milliseconds. wer: $ref: '#/components/schemas/AverageMetric' description: Word error rate of the transcription. avg_interruption: $ref: '#/components/schemas/AverageMetric' description: Average number of agent interruptions per call. tool_call_accuracy: $ref: '#/components/schemas/AverageMetric' description: Rate at which tool calls were made accurately. transition_accuracy: $ref: '#/components/schemas/AverageMetric' description: Rate at which conversation flow node transitions were correct. natural_tonality_rate: $ref: '#/components/schemas/AverageMetric' description: Rate at which the agent's speech sounded natural. custom_tool_call_latency: $ref: '#/components/schemas/AverageMetric' description: Average latency of custom tool calls, in milliseconds. custom_tool_call_success_rate: $ref: '#/components/schemas/AverageMetric' description: Success rate of custom tool calls. 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' agent_tag: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by agent environment tag(s) (e.g. "prod", "staging"). 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 description: >- A QA cohort - a saved set of call filters, sampling, and scoring criteria used to evaluate a group of calls. required: - cohort_id - name - cohort_filter - sampling_percentage - scoring_criteria - successful_criteria - total_calls - resolved_calls - analyzed_calls - evaluation_mode properties: cohort_id: type: string description: Unique identifier for the cohort. name: type: string maxLength: 100 description: User-provided name of the cohort. cohort_filter: $ref: '#/components/schemas/CohortFilter' description: >- Call filter criteria that determine which calls are included in the cohort. sampling_percentage: type: number minimum: 0.01 maximum: 100 description: Percentage of matching calls sampled for QA. sampling_weekly_max: type: number minimum: 0 description: Optional cap on the number of calls sampled per week. scoring_criteria: $ref: '#/components/schemas/ScoringCriteria' description: Metrics and custom conditions used to score each call. successful_criteria: type: object description: Score threshold a call must meet to be marked successful. required: - value - op properties: type: type: string enum: - number value: type: number minimum: 0 maximum: 100 description: Score threshold value. op: type: string enum: - gt - ge description: Comparison operator applied against `value`. total_calls: type: number description: Total number of calls matched into the cohort. resolved_calls: type: number description: Number of analyzed calls that passed the cohort's success criteria. analyzed_calls: type: number description: Number of calls that have completed QA analysis. evaluation_mode: type: string enum: - default - weighted description: >- Scoring mode - "default" weighs metrics equally, "weighted" uses each metric's configured score weight. paused: type: boolean description: Whether QA processing for this cohort is paused. ComponentNode: allOf: - $ref: '#/components/schemas/NodeBaseCommon' - type: object required: - type - component_id - component_type - else_edge properties: type: type: string enum: - component description: Type of the node component_id: type: string description: The reference ID of the component component_type: type: string enum: - local - shared description: > Type of component: - local: stored in conversation flow's components array - shared: stored in stand-alone conversation-flow-component table edges: type: array items: $ref: '#/components/schemas/NodeEdge' description: Array of edges for conditional transitions else_edge: $ref: '#/components/schemas/ElseEdge' description: Default edge when no other conditions are met finetune_transition_examples: type: array items: $ref: '#/components/schemas/NodeFinetuneTransitionExample' ConversationFlowComponentResponse: allOf: - $ref: '#/components/schemas/CreateConversationFlowComponentRequest' - type: object required: - conversation_flow_component_id - user_modified_timestamp properties: conversation_flow_component_id: type: string description: Unique identifier for the component user_modified_timestamp: type: integer format: int64 description: Timestamp of last user modification linked_conversation_flow_ids: type: array items: type: string description: IDs of conversation flows linked to this shared component Asset: type: object properties: asset_id: type: string description: Unique identifier for the asset. example: asset_abc123def456 file_name: type: string description: Original file name of the uploaded asset. example: screenshot.png content_type: type: string description: MIME type of the asset. example: image/png file_size: type: number description: File size in bytes. example: 204800 url: type: string description: CDN URL to access the asset. example: >- https://cdn.example.com/asset/org_123/asset_abc123def456/screenshot.png created_timestamp: type: number description: Unix timestamp of when the asset was created. example: 1710000000000 Note: type: object required: - id - content - display_position - size properties: id: type: string description: Unique identifier for the note. example: note_abc123 content: type: string description: >- Text content of the note, can contain refs to images in the format "" example: Remember to handle edge cases here. display_position: type: object properties: x: type: number example: 300 'y': type: number example: 150 description: Position of the note on the canvas. size: type: object properties: width: type: number example: 200 height: type: number example: 100 description: Dimensions of the note on the canvas. ConversationFlowComponent: type: object properties: name: type: string description: Name of the component example: Customer Information Collector flex_mode: type: boolean example: false description: >- If enabled, the whole component will be converted as a Single Prompt agent. nullable: true tools: type: array items: $ref: '#/components/schemas/NodeTool' description: Tools available within the component example: - type: custom name: get_customer_info description: Get customer information from database tool_id: tool_001 url: https://api.example.com/customer method: GET nullable: true mcps: type: array items: $ref: '#/components/schemas/MCP' description: A list of MCP server configurations to use for this component nullable: true nodes: type: array items: $ref: '#/components/schemas/ConversationFlowNode' description: Nodes that make up the component example: - id: collect_info type: conversation instruction: type: prompt text: Ask the customer for their name and contact information. start_node_id: type: string description: ID of the starting node example: collect_info nullable: true begin_tag_display_position: type: object properties: x: type: number example: 100 'y': type: number example: 200 description: Display position for the begin tag in the frontend nullable: true notes: type: array items: $ref: '#/components/schemas/Note' description: Visual annotations displayed on the flow canvas. nullable: true ConversationFlowNode: oneOf: - $ref: '#/components/schemas/ConversationNode' - $ref: '#/components/schemas/SubagentNode' - $ref: '#/components/schemas/EndNode' - $ref: '#/components/schemas/FunctionNode' - $ref: '#/components/schemas/CodeNode' - $ref: '#/components/schemas/TransferCallNode' - $ref: '#/components/schemas/PressDigitNode' - $ref: '#/components/schemas/BranchNode' - $ref: '#/components/schemas/SmsNode' - $ref: '#/components/schemas/ExtractDynamicVariablesNode' - $ref: '#/components/schemas/AgentSwapNode' - $ref: '#/components/schemas/MCPNode' - $ref: '#/components/schemas/ComponentNode' - $ref: '#/components/schemas/BridgeTransferNode' - $ref: '#/components/schemas/CancelTransferNode' AgentOverrideConfig: type: object properties: interruption_sensitivity: type: number minimum: 0 maximum: 1 nullable: true responsiveness: type: number minimum: 0 maximum: 1 nullable: true voice_speed: type: number minimum: 0.5 maximum: 2 nullable: true allow_dtmf_interruption: type: boolean nullable: true description: >- If set, overrides the agent-level allow_dtmf_interruption for this node only. reminder_trigger_ms: type: number minimum: 1 nullable: true description: >- If set (in milliseconds), overrides the agent-level reminder_trigger_ms for this node only. reminder_max_count: type: integer minimum: 0 nullable: true description: >- If set, overrides the agent-level reminder_max_count for this node only. Set to 0 to disable reminders for this node. 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 - last_modification_timestamp properties: conversation_flow_id: type: string description: Unique identifier for the conversation flow version: type: integer description: Version number of the conversation flow 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. 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 flex_mode: type: boolean example: false description: >- If enabled, the whole conversation flow will be converted as a Single Prompt agent. nullable: true tools: type: array items: $ref: '#/components/schemas/NodeTool' description: Tools available in the conversation flow. example: - type: custom name: get_customer_info description: Get customer information from database tool_id: tool_001 url: https://api.example.com/customer method: GET nullable: true components: type: array items: $ref: '#/components/schemas/CreateConversationFlowComponentRequest' description: Local components embedded within the conversation flow. nullable: true start_node_id: type: string example: start description: ID of the start node in the conversation flow. nullable: true default_dynamic_variables: type: object additionalProperties: type: string example: company_name: Retell Inc support_hours: 9 AM - 5 PM description: >- Default dynamic variables that can be referenced throughout the conversation flow. nullable: true begin_tag_display_position: type: object properties: x: type: number example: 100 'y': type: number example: 200 description: Display position for the begin tag in the frontend. nullable: true notes: type: array items: $ref: '#/components/schemas/Note' description: Visual annotations displayed on the flow canvas. nullable: true mcps: type: array items: $ref: '#/components/schemas/MCP' description: >- A list of MCP server configurations to use for this conversation flow. nullable: true is_transfer_llm: type: boolean example: false description: Whether this conversation flow is used for transfer LLM. nullable: true nodes: type: array items: $ref: '#/components/schemas/ConversationFlowNode' description: Array of nodes in the conversation flow. example: - id: start type: conversation instruction: type: prompt text: Greet the customer and ask how you can help them. edges: - id: edge_1 transition_condition: type: prompt prompt: Customer wants to book appointment destination_node_id: book_appointment ConversationNode: allOf: - $ref: '#/components/schemas/NodeBase' - $ref: '#/components/schemas/AgentOverrideConfig' - type: object required: - type - instruction properties: type: type: string enum: - conversation description: Type of the node instruction: $ref: '#/components/schemas/NodeInstruction' skip_response_edge: $ref: '#/components/schemas/SkipResponseEdge' always_edge: $ref: '#/components/schemas/AlwaysEdge' edges: type: array items: $ref: '#/components/schemas/NodeEdge' else_edge: $ref: '#/components/schemas/ElseEdge' 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 kb_config: type: object $ref: '#/components/schemas/KBConfig' description: >- Knowledge base configuration for RAG retrieval at the node level. If kb_instruction is set here, it overrides the flow-level kb_instruction. SubagentNode: allOf: - $ref: '#/components/schemas/NodeBase' - $ref: '#/components/schemas/AgentOverrideConfig' - type: object required: - type - instruction properties: type: type: string enum: - subagent description: Type of the node instruction: $ref: '#/components/schemas/NodeInstructionPrompt' skip_response_edge: $ref: '#/components/schemas/SkipResponseEdge' always_edge: $ref: '#/components/schemas/AlwaysEdge' edges: type: array items: $ref: '#/components/schemas/NodeEdge' else_edge: $ref: '#/components/schemas/ElseEdge' finetune_conversation_examples: type: array items: $ref: '#/components/schemas/NodeFinetuneConversationExample' finetune_transition_examples: type: array items: $ref: '#/components/schemas/NodeFinetuneTransitionExample' knowledge_base_ids: type: array items: type: string description: Knowledge base IDs for RAG (Retrieval-Augmented Generation). nullable: true kb_config: type: object $ref: '#/components/schemas/KBConfig' description: >- Knowledge base configuration for RAG retrieval at the node level. If kb_instruction is set here, it overrides the flow-level kb_instruction. tool_ids: type: array items: type: string description: >- The tool ids of the tools defined in main conversation flow or component that can be used in this subagent node. nullable: true tools: type: array items: $ref: '#/components/schemas/Tool' description: >- The tools owned by this subagent node. This includes other tool types like transfer_call, agent_swap, etc. nullable: true CpsConfig: type: object description: Calls Per Second (CPS) configuration for different telephony providers properties: twilio: type: integer nullable: true minimum: 1 maximum: 5 description: CPS limit for Twilio provider (1-5) example: 3 telnyx: type: integer nullable: true minimum: 1 maximum: 16 description: CPS limit for Telnyx provider (1-16) example: 10 custom: type: integer nullable: true minimum: 1 maximum: 150 description: >- CPS limit for custom provider (1-150). Check your custom telephony provider for CPS limits; Retell will smooth outbound dialing to fit the configured limit. 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' CreateCreditTopupInvoiceRequest: type: object required: - amount_in_cents - idempotency_key properties: amount_in_cents: type: integer description: >- Top-up amount in cents. Must be between 1000 ($10) and 1000000 ($10,000). minimum: 1000 maximum: 1000000 example: 5000 idempotency_key: type: string description: Client-generated idempotency key for duplicate request protection. minLength: 1 maxLength: 32 pattern: .*\S.* example: c0f595c6-bb6a-4f82-bf7f-923f832af7b4 CreateCreditTopupInvoiceResponse: type: object required: - invoice_id - invoice_status properties: invoice_id: type: string description: Stripe invoice id. example: in_1234567890 invoice_status: type: string description: Current Stripe invoice status. example: open invoice_url: type: string nullable: true description: Hosted Stripe invoice URL when available. example: https://invoice.stripe.com/i/acct_123/invst_123 OptInBillingV2Request: type: object required: - starting_credits properties: starting_credits: type: integer description: >- Initial prepaid credit purchase when migrating from Billing V1 to V2, in cents (same bounds as amount_in_cents on credit top-up). Charged via a one-time Stripe invoice before the migration completes. minimum: 1000 maximum: 1000000 example: 5000 OptInBillingV2Response: type: object required: - billing_profile_id - cadence_id - pricing_plan_subscription_id - starting_credits_cents properties: billing_profile_id: type: string cadence_id: type: string pricing_plan_subscription_id: type: string starting_credits_cents: type: integer description: Echo of starting_credits from the request (cents). 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". parameter_type: type: string enum: - json - form description: >- How the tool's `parameters` are authored and shown in the dashboard editor — "form" for the visual parameter builder, "json" for a raw JSON Schema. Both produce the same `parameters` schema; this does not change how the request body is encoded (see `args_at_root`). enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call. required: - type - name - url CodeTool: type: object properties: type: type: string enum: - code name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). description: type: string description: Describes what this tool does and when to call this tool. code: type: string maxLength: 20000 description: JavaScript code to execute in the sandbox. timeout_ms: type: integer minimum: 5000 maximum: 60000 description: >- The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s). response_variables: type: object additionalProperties: type: string example: order_id: data.order.id description: >- A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables. speak_during_execution: type: boolean description: >- Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool. speak_after_execution: type: boolean default: true description: >- Determines whether the agent would call LLM another time and speak when the result of function is obtained. execution_message_description: type: string description: >- The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this tool is executing. required: - type - name - code 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' SmsUtterance: type: object required: - role - content - time_sec properties: role: type: string enum: - sms description: >- SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation. content: type: string description: Text content of the SMS message. multimedia: type: array items: $ref: '#/components/schemas/SmsMultimediaItem' description: >- Multimedia attachments (MMS). Display only; not relayed into the spoken conversation. time_sec: type: number description: >- Time the SMS was received, in seconds relative to the start of the call. InjectedUtterance: type: object required: - role - content - time_sec properties: role: type: string enum: - injected description: >- External context injected into the conversation via the update-live-call API. Not spoken by either party. content: type: string description: The injected context text. time_sec: type: number description: >- Time the context was injected, in seconds relative to the start of the call. SmsMultimediaItem: type: object required: - url properties: url: type: string description: URL of the multimedia attachment. summary: type: string description: Optional textual summary of the attachment. 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 minProperties: 1 properties: name: type: string description: The tool call name to filter on. type: type: string description: The tool call type 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. agent_tag: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by agent environment tag(s) (e.g. "prod", "staging"). call_id: oneOf: - $ref: '#/components/schemas/StringFilter' - $ref: '#/components/schemas/EnumFilter' 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. ChatFilter: type: object description: >- Filter criteria for chats. 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. agent_tag: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by agent environment tag(s) (e.g. "prod", "staging"). chat_id: $ref: '#/components/schemas/StringFilter' description: Filter by chat ID. chat_status: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by chat status. properties: value: items: enum: - ongoing - ended - error disconnection_reason: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by disconnection reason. properties: value: items: $ref: '#/components/schemas/DisconnectionReason' user_sentiment: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by user sentiment. properties: value: items: enum: - Negative - Positive - Neutral - Unknown chat_successful: $ref: '#/components/schemas/BooleanFilter' description: Filter by whether the chat was successful. start_timestamp: oneOf: - $ref: '#/components/schemas/NumberFilter' - $ref: '#/components/schemas/RangeFilter' description: Filter by chat start timestamp (epoch ms). end_timestamp: oneOf: - $ref: '#/components/schemas/NumberFilter' - $ref: '#/components/schemas/RangeFilter' description: Filter by chat end timestamp (epoch ms). duration_ms: oneOf: - $ref: '#/components/schemas/NumberFilter' - $ref: '#/components/schemas/RangeFilter' description: Filter by chat duration in milliseconds. combined_cost: oneOf: - $ref: '#/components/schemas/NumberFilter' - $ref: '#/components/schemas/RangeFilter' description: Filter by combined cost of the chat. 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. 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_concurrency_fallback - 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 - manual_stopped - call_take_over Duration: type: object required: - start_sec - end_sec properties: start_sec: type: number description: Start time in seconds end_sec: type: number description: End time in seconds ElseEdge: allOf: - $ref: '#/components/schemas/NodeEdge' - type: object required: - transition_condition properties: transition_condition: type: object required: - type - prompt properties: type: type: string enum: - prompt prompt: type: string enum: - Else description: Must be "Else" for else edge EndCallTool: type: object properties: type: type: string enum: - end_call name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state transitions). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). description: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. speak_during_execution: type: boolean description: If true, will speak during execution. execution_message_description: type: string description: >- Describes what to say to user when ending the call. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". required: - type - name EndNode: allOf: - $ref: '#/components/schemas/NodeBase' - type: object required: - type properties: type: type: string enum: - end description: Type of the node speak_during_execution: type: boolean description: If true, will speak during execution instruction: $ref: '#/components/schemas/NodeInstruction' description: >- What to say when ending the call, only used when speak during execution EnumAnalysisData: type: object required: - type - name - description - choices properties: type: type: string enum: - enum description: Type of the variable to extract. example: enum name: type: string description: Name of the variable. example: product_rating minLength: 1 description: type: string description: Description of the variable. example: Rating of the product. choices: type: array items: type: string description: The possible values of the variable, must be non empty array. example: - good required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. EquationCondition: type: object required: - type - equations - operator properties: type: type: string enum: - equation equations: type: array maxItems: 50 items: $ref: '#/components/schemas/Equation' operator: type: string enum: - '||' - '&&' Equation: type: object required: - left - operator properties: left: type: string description: Left side of the equation operator: type: string enum: - '==' - '!=' - '>' - '>=' - < - <= - contains - not_contains - exists - not_exist right: type: string description: >- Right side of the equation. The right side of the equation not required when "exists" or "not_exist" are selected. ExtractDynamicVariableTool: type: object properties: type: type: string enum: - extract_dynamic_variable name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). description: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. variables: type: array items: $ref: '#/components/schemas/AnalysisData' description: The variables to be extracted. enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this tool is executing. required: - type - name - 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' enable_typing_sound: type: boolean description: If true, play a typing sound while this extract step executes. 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 enable_typing_sound: type: boolean description: If true, play a typing sound while this function executes. 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 maxLength: 20000 description: JavaScript code to execute in the sandbox. timeout_ms: type: integer minimum: 5000 maximum: 60000 description: >- The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s). response_variables: type: object additionalProperties: type: string example: order_id: data.order.id description: >- A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables. speak_during_execution: type: boolean description: Whether to speak during code execution instruction: $ref: '#/components/schemas/NodeInstruction' wait_for_result: type: boolean description: Whether to wait for code execution result enable_typing_sound: type: boolean description: If true, play a typing sound while code executes. 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 description: Analysis of agent hallucinations across utterances. required: - details - hallucination_utterance_count - total_utterance_count properties: details: type: array items: $ref: '#/components/schemas/UtteranceHallucination' hallucination_utterance_count: type: number description: Number of utterances containing a hallucination. total_utterance_count: type: number description: Total number of agent utterances evaluated. InterruptionAnalysis: type: object description: Analysis of the agent interrupting the user. required: - details - interruption_count properties: details: type: array items: $ref: '#/components/schemas/Duration' description: Time spans where the agent interrupted the user. interruption_count: type: number description: Total number of times the agent interrupted the user. 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. file_size: type: number description: File size in bytes. 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. LanguageLegacy: oneOf: - $ref: '#/components/schemas/Language' - type: string enum: - multi example: en-US description: >- Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`. 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 description: >- Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. This enum does not include the legacy scalar value `multi`. 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 - gpt-5.5 - gpt-5.6-terra - gpt-5.6-luna - claude-4.5-sonnet - claude-4.6-sonnet - claude-5-sonnet - claude-4.5-haiku - gemini-3.0-flash - gemini-3.1-flash-lite - gemini-3.5-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 enable_typing_sound: type: boolean description: If true, play a typing sound while MCP tool executes. 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. 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". enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this MCP tool is executing. required: - type - name - description 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' - $ref: '#/components/schemas/InjectedMessage' - $ref: '#/components/schemas/SmsMessage' ChatMessageInput: description: >- Same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted. oneOf: - $ref: '#/components/schemas/MessageBase' - $ref: '#/components/schemas/ToolCallInvocationMessageBase' - $ref: '#/components/schemas/ToolCallResultMessageBase' - $ref: '#/components/schemas/NodeTransitionMessageBase' - $ref: '#/components/schemas/StateTransitionMessageBase' - $ref: '#/components/schemas/InjectedMessageBase' - $ref: '#/components/schemas/SmsMessageBase' MessageBase: type: object required: - role - content 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 Message: allOf: - $ref: '#/components/schemas/MessageBase' - required: - message_id - created_timestamp InjectedMessageBase: type: object required: - role - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - injected description: >- External context injected into the conversation via the update-live-call API. Not spoken by either party. content: type: string description: The injected context text. example: Customer just opened a support ticket about billing. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 InjectedMessage: allOf: - $ref: '#/components/schemas/InjectedMessageBase' - required: - message_id - created_timestamp SmsMessageBase: type: object required: - role - content properties: message_id: type: string example: Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6 description: Unique id of the message role: type: string enum: - sms description: >- SMS message exchanged during the call (for example received from the user). Woven into the transcript and shown to the agent, but not part of the spoken conversation. content: type: string description: Text content of the SMS message. example: Here is the photo you asked for. multimedia: type: array items: $ref: '#/components/schemas/SmsMultimediaItem' description: >- Multimedia attachments (MMS). Display only; not relayed into the spoken conversation. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 SmsMessage: allOf: - $ref: '#/components/schemas/SmsMessageBase' - required: - message_id - created_timestamp 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 reason: type: string description: >- Explanation of why the metric passed or failed. Set for custom-condition metrics. vote: type: boolean description: An optional vote based on the metric result. TranscriptionErrorAnalysis: type: object description: >- Transcription error analysis for a call, covering mistranscribed important entities and the overall word error rate. required: - details - mie_utterance_count - total_utterance_count - overall_wer properties: details: type: array items: $ref: '#/components/schemas/UtteranceTranscriptionError' mie_utterance_count: type: number description: Number of utterances containing a mistranscribed important entity. total_utterance_count: type: number overall_wer: $ref: '#/components/schemas/WER' description: Word error rate aggregated across the whole call. UtteranceTranscriptionError: type: object description: Transcription error details for a single utterance. required: - duration - mie_details - wer properties: duration: $ref: '#/components/schemas/Duration' description: Time span of the utterance within the call. mie_details: type: array description: Mistranscribed important entities found in the utterance. items: type: object required: - original_transcript - corrected_transcript - start_sec - end_sec properties: original_transcript: type: string description: The original (mistranscribed) transcript segment. corrected_transcript: type: string description: The corrected transcript segment. start_sec: type: number description: Start time of the segment in seconds. end_sec: type: number description: End time of the segment in seconds. wer: $ref: '#/components/schemas/WER' description: Word error rate for this utterance. 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: - AudioArtifacts - Mispronunciation - PoorArticulation - UnnaturalPacing - UnnaturalIntonation - 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 SmsInstructionTemplate: type: object required: - type - template properties: type: type: string enum: - template description: Type of instruction template: type: string enum: - info_collection description: >- The template to use for the instruction. "info_collection" sends a predefined message requesting information from the user. 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 description: Conversation flow node transition accuracy analysis. required: - details - correct_count - total_count properties: details: type: array description: Per-transition audit results. items: type: object required: - time_sec - accurate properties: time_sec: type: number description: Time of the transition relative to the call start. accurate: type: boolean correct_node_id: type: number description: ID of the node that should have been selected. reasoning: type: string description: Explanation of why the transition was inaccurate. correct_count: type: number total_count: type: number NodeTransitionMessageBase: type: object required: - role 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 transition_type: type: string enum: - global - global_go_back - interrupt_go_back - normal description: >- How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition. created_timestamp: type: integer description: Create timestamp of the message example: 1703302428855 NodeTransitionMessage: allOf: - $ref: '#/components/schemas/NodeTransitionMessageBase' - required: - message_id - created_timestamp 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 transition_type: type: string enum: - global - global_go_back - interrupt_go_back - normal description: >- How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition. 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 - gpt-5.5 - gpt-5.6-terra - gpt-5.6-luna - claude-4.5-sonnet - claude-4.6-sonnet - claude-5-sonnet - claude-4.5-haiku - gemini-3.0-flash - gemini-3.1-flash-lite - gemini-3.5-flash - null nullable: true description: Available LLM models for agents. NumberAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - number description: Type of the variable to extract. example: number name: type: string description: Name of the variable. example: order_count minLength: 1 description: type: string description: Description of the variable. example: How many the customer intend to order. required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. PresetAnalysisData: type: object required: - type - name - description description: >- System preset for post-call or post-chat analysis (summary, success, sentiment). Presets can be included in post_call_analysis_data or post_chat_analysis_data to override prompts or mark fields optional. properties: type: type: string enum: - system-presets description: Identifies this item as a system preset. name: type: string enum: - call_summary - call_successful - chat_summary - chat_successful - user_sentiment description: >- Preset identifier. Use call_summary/call_successful for voice; chat_summary/chat_successful for chat; user_sentiment for both. example: call_summary description: type: string minLength: 1 description: Prompt or description for this preset. required: type: boolean description: >- If false, this field is optional in the analysis. If true or unset, the field is required. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. CallPresetAnalysisData: type: object required: - type - name description: >- System preset for post-call analysis (voice agents). Use in post_call_analysis_data to override prompts or mark fields optional. properties: type: type: string enum: - system-presets description: Identifies this item as a system preset. name: type: string enum: - call_summary - call_successful - user_sentiment description: Preset identifier for voice agent analysis. example: call_summary description: type: string minLength: 1 description: Prompt or description for this preset. required: type: boolean description: >- If false, this field is optional in the analysis. If true or unset, the field is required. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. ChatPresetAnalysisData: type: object required: - type - name description: >- System preset for post-chat analysis (chat agents). Use in post_chat_analysis_data to override prompts or mark fields optional. properties: type: type: string enum: - system-presets description: Identifies this item as a system preset. name: type: string enum: - chat_summary - chat_successful - user_sentiment description: Preset identifier for chat agent analysis. example: chat_summary description: type: string minLength: 1 description: Prompt or description for this preset. required: type: boolean description: >- If false, this field is optional in the analysis. If true or unset, the field is required. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. Organization: type: object properties: org_name: type: string description: Name of the organization example: My Organization minLength: 1 maxLength: 100 orgName: type: string description: Name of the organization example: My Organization minLength: 1 maxLength: 100 outage_mode_enabled: type: boolean description: Whether outage mode is enabled webhook_urls: type: array items: type: object properties: url: type: string timeout_ms: type: integer webhook_key: type: string description: API key for webhook authentication concurrency: type: integer description: Maximum concurrent calls allowed reserved_inbound_concurrency: type: integer minimum: 0 description: >- Number of concurrency slots reserved for inbound calls. Outbound calls can use at most the remaining concurrency; inbound calls can still use the full org concurrency limit when capacity is available. 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 auto_credit_reload_config: $ref: '#/components/schemas/AutoCreditReloadConfig' enterprise_id: type: string feature_bucket: type: object use_stable_server: type: boolean conductor_overage: $ref: '#/components/schemas/ConductorOverageConfig' OrganizationResponse: allOf: - $ref: '#/components/schemas/Organization' - type: object properties: org_id: type: string description: Unique identifier of the organization AutoCreditReloadConfig: type: object description: >- Both values are in cents. `target_amount` must be strictly greater than `threshold`, and the gap must be at least 1000 cents ($10). required: - threshold - target_amount properties: threshold: type: number description: >- Trigger auto reload when balance is <= threshold (in cents). Must be a positive number. minimum: 0 exclusiveMinimum: true target_amount: type: number description: >- Target balance to reach after auto reload (in cents). Must be a positive number, strictly greater than `threshold`, and at least 1000 cents ($10) above `threshold`. minimum: 1000 maximum: 5000000 exclusiveMinimum: true example: threshold: 10000 target_amount: 25000 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. PII redaction is only active when this list is non-empty; an empty array means no PII scrubbing is performed. GuardrailConfig: type: object properties: output_topics: type: array items: type: string enum: - harassment - self_harm - sexual_exploitation - violence - defense_and_national_security - illicit_and_harmful_activity - gambling - regulated_professional_advice - child_safety_and_exploitation uniqueItems: true description: >- Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message. nullable: true input_topics: type: array items: type: string enum: - platform_integrity_jailbreaking uniqueItems: true description: >- Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request. nullable: true VoiceHandbookConfig: type: object description: Behavior presets for voice agents. All presets are available. properties: default_personality: type: boolean description: Professional call center rep baseline. conversational_personality: type: boolean description: >- Enables Conversational Personality. When true, the agent uses the Conversational Personality handbook preset, skips Professional Rep Personality during prompt assembly, and enables internal colloquial rewrite behavior. natural_filler_words: type: boolean description: >- Sprinkle natural speech fillers like "um", "you know" for a more human, conversational tone. high_empathy: type: boolean description: Warm acknowledgment of caller concerns. echo_verification: type: boolean description: Repeat back and confirm important details (voice only). nato_phonetic_alphabet: type: boolean description: Spell using NATO phonetic alphabet style (voice only). speech_normalization: type: boolean description: Convert numbers/dates/currency to spoken forms (voice only). smart_matching: type: boolean description: >- Treat near-match similar words as same entity to reduce impact of transcription error (voice only). ai_disclosure: type: boolean description: When asked, acknowledge being a virtual assistant. scope_boundaries: type: boolean description: Stay within prompt/context scope, don't invent details. ChatHandbookConfig: type: object description: Behavior presets for chat agents. Voice-only presets are excluded. properties: default_personality: type: boolean description: Professional call center rep baseline. high_empathy: type: boolean description: Warm acknowledgment of caller concerns. ai_disclosure: type: boolean description: When asked, acknowledge being a virtual assistant. scope_boundaries: type: boolean description: Stay within prompt/context scope, don't invent details. PerformanceMetricCriteria: type: object required: - metric_type - op - value - score_weight properties: metric_type: type: object description: Performance metric type op: type: string enum: - gt - gte - ge - lt - lte - le - eq - ne description: Comparison operator for filtering value: type: number description: Threshold compared against the performance metric. 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. 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. 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. 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. 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. 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, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure other fields specific to that call. nullable: true inbound_sms_webhook_url: type: string example: https://example.com/inbound-sms-webhook description: >- If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, reject the SMS, and configure 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: >- When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. 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' else_edge: $ref: '#/components/schemas/ElseEdge' 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). call_id: oneOf: - $ref: '#/components/schemas/StringFilter' - $ref: '#/components/schemas/EnumFilter' description: Filter by call ID. 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' agent_tag: allOf: - $ref: '#/components/schemas/EnumFilter' - description: Filter by agent environment tag(s) (e.g. "prod", "staging"). 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.' CohortQaListArgs: type: object description: Sorting and pagination options for listing a cohort's call QAs. properties: sort_key: type: string enum: - call_id - duration_ms - e2e_latency_p50 - score - interruption_count - llm_hallucination_rate - kb_recall - transition_accuracy - user_positive_sentiment_rate - user_negative_sentiment_rate - wer - tool_call_accuracy - natural_tonality_rate description: Field to sort by. Defaults to "score". limit: type: integer minimum: 1 maximum: 1000 description: Maximum number of records to return. Defaults to 1000. order: type: string enum: - asc - desc description: Sort order. skip: type: integer minimum: 0 description: Number of records to skip for pagination. RAGAccuracy: type: object description: Knowledge base retrieval accuracy for one agent response. required: - false_positive - false_negative - true_positive properties: response_id: type: number false_positive: type: number description: Number of chunks retrieved during the call but deemed irrelevant. false_negative: type: number description: Number of relevant chunks that were not retrieved during the call. true_positive: type: number description: Number of chunks retrieved during the call and deemed relevant. missed_chunks: type: array description: Relevant knowledge base chunks that were not retrieved. items: type: object required: - chunk_id properties: chunk_id: type: string chunk: type: string description: Content of the missed chunk. RAGAnalysis: type: object description: Knowledge base retrieval accuracy and recall analysis. required: - details - rag_accurate_count - rag_full_recall_count - rag_total_count properties: details: type: array items: $ref: '#/components/schemas/RAGAccuracy' rag_accurate_count: type: number description: Number of responses with accurate retrieval. rag_full_recall_count: type: number description: Number of responses with full chunk recall. rag_total_count: type: number description: Total number of retrieval events evaluated. 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-2.1 - gpt-realtime-2.1-mini - gpt-realtime-2 - 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 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 description: Natural-language conditions evaluated against each call. items: type: object required: - description - score_weight properties: description: type: string description: Natural-language condition to evaluate. score_weight: type: number minimum: 1 maximum: 100 performance_metrics: type: array items: $ref: '#/components/schemas/PerformanceMetricCriteria' SendSMSTool: type: object properties: name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). type: type: string enum: - send_sms description: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. speak_during_execution: type: boolean description: >- If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools). execution_message_description: type: string description: >- Describes what to say before sending the SMS. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". sms_content: $ref: '#/components/schemas/SmsContent' required: - type - name - sms_content SmsSender: oneOf: - type: object required: - type properties: type: type: string enum: - current_number - type: object required: - type properties: type: type: string enum: - retell_long_code SmsDestination: oneOf: - type: object required: - type properties: type: type: string enum: - customer_number - type: object required: - type - phone_number properties: type: type: string enum: - phone_number phone_number: type: string description: Destination phone number in E.164 format. ignore_e164_validation: type: boolean description: >- If true, skip E.164 validation for this phone number (same semantics as transfer_call ignore_e164_validation). SentimentAnalysis: type: object description: Per-utterance sentiment analysis with aggregate counts. required: - details - positive_count - neutral_count - negative_count properties: details: type: array description: >- Per-utterance sentiment results, identified by either a time range or response ID. items: oneOf: - type: object properties: duration: $ref: '#/components/schemas/Duration' sentiment: type: string description: Sentiment detected during the time range. enum: - Positive - Neutral - Negative - type: object properties: response_id: type: number description: >- Identifier of the response associated with the evaluated utterance. sentiment: type: string description: Sentiment detected for the response. 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 text: type: string description: >- The static message to be sent in the SMS. Can contain dynamic variables. SmsContentTemplate: type: object required: - type - template properties: type: type: string enum: - template template: type: string enum: - info_collection description: >- The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user. SmsContent: oneOf: - $ref: '#/components/schemas/SmsContentPredefined' - $ref: '#/components/schemas/SmsContentInferred' - $ref: '#/components/schemas/SmsContentTemplate' 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: oneOf: - $ref: '#/components/schemas/NodeInstruction' - $ref: '#/components/schemas/SmsInstructionTemplate' 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. StateTransitionMessageBase: type: object required: - role 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 StateTransitionMessage: allOf: - $ref: '#/components/schemas/StateTransitionMessageBase' - required: - message_id - created_timestamp State: type: object required: - name properties: name: example: information_collection type: string description: >- Name of the state, must be unique for each state. Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). state_prompt: example: |- ## Task You will follow the steps below... type: string description: | Prompt of the state, will be appended to the system prompt of LLM. - System prompt = general prompt + state prompt. edges: type: array items: $ref: '#/components/schemas/StateEdge' description: >- Edges of the state define how and what state can be reached from this state. tools: type: array items: $ref: '#/components/schemas/Tool' description: > A list of tools specific to this state the model may call (to get external knowledge, call API, etc). You can select from some common predefined tools like end call, transfer call, etc; or you can create your own custom tool for the LLM to use. - Tools of LLM = general tools + state tools + state transitions StringAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - string description: Type of the variable to extract. example: string name: type: string description: Name of the variable. example: customer_name minLength: 1 description: type: string description: Description of the variable. example: The name of the customer. examples: type: array items: type: string description: Examples of the variable value to teach model the style and syntax. example: - John Doe - Jane Smith required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. TestCaseBatchJob: type: object required: - test_case_batch_job_id - status - response_engine - pass_count - fail_count - error_count - total_count - creation_timestamp - user_modified_timestamp properties: test_case_batch_job_id: type: string description: Unique identifier for the test case batch job status: type: string enum: - in_progress - complete description: Status of the batch job response_engine: $ref: '#/components/schemas/ResponseEngine' pass_count: type: integer description: Number of test cases that passed minimum: 0 fail_count: type: integer description: Number of test cases that failed minimum: 0 error_count: type: integer description: Number of test cases that encountered errors minimum: 0 total_count: type: integer description: Total number of test cases in the batch minimum: 0 creation_timestamp: type: integer description: Timestamp when the batch job was created (milliseconds since epoch) user_modified_timestamp: type: integer description: >- Timestamp when the batch job was last modified (milliseconds since epoch) TestCaseDefinitionInput: type: object properties: name: type: string description: Name of the test case definition response_engine: $ref: '#/components/schemas/RetellResponseEngine' description: >- Response engine to use for the test case. Custom LLM is not supported. user_prompt: type: string description: User prompt to simulate in the test case metrics: type: array items: type: string description: Array of metric names to evaluate dynamic_variables: type: object additionalProperties: type: string description: Dynamic variables to inject into the response engine tool_mocks: type: array items: $ref: '#/components/schemas/ToolMock' description: Mock tool calls for testing llm_model: $ref: '#/components/schemas/LLMModel' description: LLM model to use for simulation TestCaseDefinition: allOf: - $ref: '#/components/schemas/TestCaseDefinitionInput' - type: object required: - name - response_engine - metrics - user_prompt - dynamic_variables - tool_mocks - llm_model - test_case_definition_id - type - creation_timestamp - user_modified_timestamp properties: test_case_definition_id: type: string description: Unique identifier for the test case definition type: type: string enum: - simulation description: Type of test case definition creation_timestamp: type: integer description: >- Timestamp when the test case definition was created (milliseconds since epoch) user_modified_timestamp: type: integer description: >- Timestamp when the test case definition was last modified (milliseconds since epoch) TestCaseJob: type: object required: - test_case_job_id - status - test_case_definition_id - test_case_definition_snapshot - creation_timestamp - user_modified_timestamp properties: test_case_job_id: type: string description: Unique identifier for the test case job status: type: string enum: - pending - in_progress - pass - fail - error description: >- Status of the test case job. `pending` means the run is queued but has not started yet; it becomes `in_progress` once a worker picks it up, then resolves to `pass`, `fail`, or `error`. 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 RetellLlmPlaygroundSnapshot 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: description: >- Decides which calls to the tool this mock applies to, based on the arguments the LLM passes to the tool. oneOf: - type: object required: - type properties: type: type: string enum: - any description: >- Match every call to the tool, no matter what arguments were passed. Use this for a catch-all mock. - type: object required: - type - args properties: type: type: string enum: - partial_match description: >- Match only calls whose arguments contain the values listed in `args`. args: type: object description: >- Argument values the call must have to match. Only the fields you list here are checked, and each must equal the value in the actual call. Extra fields in the call are ignored, so this is a subset match. ToolMock: description: >- A fake response for one tool. During a simulation, when the LLM calls a tool whose name matches `tool_name` and whose arguments satisfy `input_match_rule`, the real tool is not run; `output` is returned to the LLM instead. This keeps runs deterministic and avoids calling live integrations. A tool call that matches no mock falls through to the real tool. type: object required: - tool_name - input_match_rule - output properties: tool_name: type: string description: >- The tool's function name, not the tool ID, i.e. the name the LLM uses when it calls the tool (for example `check_availability_cal`, `book_appointment_cal`, or the name you gave a custom function). input_match_rule: $ref: '#/components/schemas/ToolMockInputMatchRule' description: Decides which calls to this tool the mock applies to. output: type: string maxLength: 15000 description: >- The tool result fed back to the LLM in place of the real tool's output. Should be a JSON string, the same shape the real tool would return. 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 description: Analysis of whether tool calls were made accurately. 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 ToolCallMetricAnalysis: type: object description: >- Per-invocation latency and success outcomes for a group of tool calls (e.g. custom tools or transfer calls). required: - successful - latency properties: successful: type: array items: type: boolean description: Whether each tool call succeeded, in invocation order. latency: type: array items: type: number description: Latency of each tool call in milliseconds, in invocation order. ToolCallInvocationMessageBase: type: object required: - 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 ToolCallInvocationMessage: allOf: - $ref: '#/components/schemas/ToolCallInvocationMessageBase' - required: - message_id - created_timestamp 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. ToolCallResultMessageBase: type: object required: - role - tool_call_id - content 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 ToolCallResultMessage: allOf: - $ref: '#/components/schemas/ToolCallResultMessageBase' - required: - message_id - created_timestamp 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 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 - custom description: >- The music to play while the caller is being transferred. Use `custom` together with `custom_on_hold_music_asset_id` to play an uploaded audio asset. custom_on_hold_music_asset_id: type: string description: >- Asset ID of the uploaded hold music to play. Required when `on_hold_music` is `custom`. Must reference an audio asset owned by the organization (see create-asset). example: asset_abc123def456 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: $ref: '#/components/schemas/AgentVersionReference' 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 - custom description: >- The music to play while the caller is being transferred. Use `custom` together with `custom_on_hold_music_asset_id` to play an uploaded audio asset. custom_on_hold_music_asset_id: type: string description: >- Asset ID of the uploaded hold music to play. Required when `on_hold_music` is `custom`. Must reference an audio asset owned by the organization (see create-asset). example: asset_abc123def456 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: type: object description: Partial update for PATCH /update-organization. All fields optional. properties: org_name: type: string description: Name of the organization minLength: 1 maxLength: 100 orgName: type: string description: Name of the organization (legacy field) minLength: 1 maxLength: 100 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. reserved_inbound_concurrency: type: integer minimum: 0 description: >- Number of concurrency slots reserved for inbound calls. Must be less than total normal concurrency. auto_credit_reload_config: type: object nullable: true description: >- Auto reload configuration. Set to null to clear existing config. Both values are in cents. `target_amount` must be strictly greater than `threshold`, and the gap must be at least 1000 cents ($10). properties: threshold: type: number description: >- Trigger auto reload when balance is <= threshold (in cents). Must be a positive number. minimum: 0 exclusiveMinimum: true target_amount: type: number description: >- Target balance to reach after auto reload (in cents). Must be strictly greater than `threshold` and at least 1000 cents ($10) above `threshold`. minimum: 1000 maximum: 5000000 exclusiveMinimum: true conductor_overage: $ref: '#/components/schemas/ConductorOverageConfig' SpendBudgetCustomAlertRequest: type: object required: - percentage - recipients properties: percentage: type: integer minimum: 1 maximum: 99 recipients: type: array items: type: string UpdateSpendBudgetRequest: oneOf: - description: Disable spend budget. type: object required: - enabled properties: enabled: type: boolean enum: - false additionalProperties: false - description: Enable spend budget (monthly cap required). type: object required: - enabled - monthly_budget_cents - custom_alerts properties: enabled: type: boolean enum: - true monthly_budget_cents: type: integer minimum: 0 exclusiveMinimum: true description: Monthly spend cap in cents (greater than 0). custom_alerts: type: array maxItems: 5 items: $ref: '#/components/schemas/SpendBudgetCustomAlertRequest' additionalProperties: false UserFormRequest: type: object required: - form properties: form: type: object additionalProperties: type: string description: A JSON object containing survey form data with string values utm_parameters: type: object additionalProperties: type: string description: UTM tracking parameters referrer: type: string description: Referrer URL UtteranceHallucination: type: object description: Hallucination details for a single agent utterance. required: - response_id properties: response_id: type: number hallucination_type: type: string enum: - Fabrication - Contradiction - Confusion description: Type of hallucination detected. explanation: type: string description: Explanation of the hallucination. low_severity: type: boolean description: True for minor hallucinations; false or omitted for major ones. UtteranceNaturalnessIssues: type: object required: - response_id - naturalness_issues properties: response_id: type: number naturalness_issues: type: array items: $ref: '#/components/schemas/NaturalnessIssue' reason: type: string description: Explanation of the naturalness issues found in the utterance. UtteranceOrToolCall: oneOf: - $ref: '#/components/schemas/Utterance' - $ref: '#/components/schemas/ToolCallInvocationUtterance' - $ref: '#/components/schemas/ToolCallResultUtterance' - $ref: '#/components/schemas/NodeTransitionUtterance' - $ref: '#/components/schemas/DTMFUtterance' - $ref: '#/components/schemas/SmsUtterance' - $ref: '#/components/schemas/InjectedUtterance' 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 description: Tool calls made with incorrect arguments. 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. agent_tag: type: string example: prod nullable: true description: >- Tag pointing at the agent version used for this call, captured at call creation time and frozen thereafter (unaffected by later tag reassignments). Populated whether the caller dispatched by tag, numeric version, "latest", or "latest_published" — when the caller specified a tag, that tag wins; otherwise the most-recently- assigned tag on the resolved version is used. Absent when no tag points at the resolved version (or for calls created before this field was introduced). 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: type: string 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: type: string 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' V3CallResponse: oneOf: - $ref: '#/components/schemas/V3WebCallResponse' - $ref: '#/components/schemas/V3PhoneCallResponse' V3CallBase: 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. agent_tag: type: string example: prod nullable: true description: >- Tag pointing at the agent version used for this call, captured at call creation time and frozen thereafter (unaffected by later tag reassignments). Populated whether the caller dispatched by tag, numeric version, "latest", or "latest_published" — when the caller specified a tag, that tag wins; otherwise the most-recently- assigned tag on the resolved version is used. Absent when no tag points at the resolved version (or for calls created before this field was introduced). 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: type: string 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: type: string 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. 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. V3PhoneCallResponse: 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/V3CallBase' V3WebCallResponse: 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/V3CallBase' V3ListCallsRequest: type: object properties: filter_criteria: $ref: '#/components/schemas/CallFilter' sort_order: type: string enum: - ascending - descending default: descending description: Sort calls by `start_timestamp` in ascending or descending order. limit: type: integer default: 50 maximum: 1000 description: Maximum number of calls to return. skip: type: integer minimum: 0 default: 0 description: Number of records to skip for pagination. pagination_key: type: string description: Opaque pagination cursor from a previous response. include_total: type: boolean default: false description: >- Whether to include `total` (count of all calls matching `filter_criteria`, ignoring `limit`/`skip`/`pagination_key`) in the response. Defaults to false. Each enabled request triggers an additional aggregate query, so opt in only when the total is needed. not: required: - skip - pagination_key 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 - 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' CallScreeningOption: type: object properties: agent_identity: type: string minLength: 1 maxLength: 100 example: Acme Health scheduling team description: >- Identity the agent should provide when a call screen asks who is calling. Dynamic variables are supported. call_purpose: type: string minLength: 1 maxLength: 300 example: confirming your appointment for tomorrow description: >- Purpose the agent should provide when a call screen asks why it is calling. Dynamic variables are supported. required: - agent_identity - call_purpose additionalProperties: false description: >- If this option is set, the agent prompt will include call screen handling instructions for identity and call purpose questions. Set this to null to disable call screen prompt instructions. nullable: true 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. ConductorOverageConfig: description: > Conductor overage policy applied once the per-user/per-org daily free limits are exhausted. "off" rejects requests past the daily limit; "limited" allows up to `monthly_limit_usd` (USD) of metered overage per month; "unlimited" allows metered overage with no monthly cap. oneOf: - type: object additionalProperties: false required: - mode properties: mode: type: string enum: - 'off' - type: object additionalProperties: false required: - mode properties: mode: type: string enum: - unlimited - type: object additionalProperties: false required: - mode - monthly_limit_usd properties: mode: type: string enum: - limited monthly_limit_usd: type: integer minimum: 0 maximum: 10000 description: Max metered overage per month, in USD (max 10000). DashboardSource: type: string enum: - call - chat ChartGroupItem: oneOf: - type: object required: - type properties: type: type: string enum: - time - agent_id - batch_call_id - call_successful - call_status - user_sentiment - disconnection_reason - direction - chat_successful - chat_status - call_type - agent_version - type: object required: - type - field properties: type: type: string enum: - custom_analysis_data - custom_attribute field: type: string 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const knowledgeBaseResponse = await client.knowledgeBase.addSources('kb_1234567890'); console.log(knowledgeBaseResponse.knowledge_base_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) knowledge_base_response = client.knowledge_base.add_sources( knowledge_base_id="kb_1234567890", ) print(knowledge_base_response.knowledge_base_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const agentResponse = await client.agent.create({ response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' }, voice_id: 'retell-Cimo', }); console.log(agentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) agent_response = client.agent.create( response_engine={ "llm_id": "llm_234sdertfsdsfsdf", "type": "retell-llm", }, voice_id="retell-Cimo", ) print(agent_response.agent_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const batchCallResponse = await client.batchCall.createBatchCall({ from_number: '+14157774444', tasks: [{ to_number: '+12137774445' }], }); console.log(batchCallResponse.batch_call_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) batch_call_response = client.batch_call.create_batch_call( from_number="+14157774444", tasks=[{ "to_number": "+12137774445" }], ) print(batch_call_response.batch_call_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const batchTestResponse = await client.tests.createBatchTest({ response_engine: { llm_id: 'llm_id', type: 'retell-llm' }, test_case_definition_ids: ['string'], }); console.log(batchTestResponse.test_case_batch_job_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) batch_test_response = client.tests.create_batch_test( response_engine={ "llm_id": "llm_id", "type": "retell-llm", }, test_case_definition_ids=["string"], ) print(batch_test_response.test_case_batch_job_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const testCaseDefinitionResponse = await client.tests.createTestCaseDefinition({ metrics: ['string'], name: 'name', response_engine: { llm_id: 'llm_id', type: 'retell-llm' }, user_prompt: 'user_prompt', }); console.log(testCaseDefinitionResponse.test_case_definition_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) test_case_definition_response = client.tests.create_test_case_definition( metrics=["string"], name="name", response_engine={ "llm_id": "llm_id", "type": "retell-llm", }, user_prompt="user_prompt", ) print(test_case_definition_response.test_case_definition_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.tests.deleteTestCaseDefinition('test_case_definition_id'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.tests.delete_test_case_definition( "test_case_definition_id", ) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const testCaseDefinitionResponse = await client.tests.getTestCaseDefinition( 'test_case_definition_id', ); console.log(testCaseDefinitionResponse.test_case_definition_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) test_case_definition_response = client.tests.get_test_case_definition( "test_case_definition_id", ) print(test_case_definition_response.test_case_definition_id) /v2/list-test-case-definitions: get: description: List test case definitions with pagination 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) - $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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.tests.listTestCaseDefinitions({ type: 'retell-llm' }); console.log(response.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.tests.list_test_case_definitions( type="retell-llm", ) print(response.has_more) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const testCaseDefinitionResponse = await client.tests.updateTestCaseDefinition( 'test_case_definition_id', ); console.log(testCaseDefinitionResponse.test_case_definition_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) test_case_definition_response = client.tests.update_test_case_definition( test_case_definition_id="test_case_definition_id", ) print(test_case_definition_response.test_case_definition_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const batchTestResponse = await client.tests.getBatchTest('test_case_batch_job_id'); console.log(batchTestResponse.test_case_batch_job_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) batch_test_response = client.tests.get_batch_test( "test_case_batch_job_id", ) print(batch_test_response.test_case_batch_job_id) /v2/list-batch-tests: get: description: List batch test jobs with pagination 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) - $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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.tests.listBatchTests({ type: 'retell-llm' }); console.log(response.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.tests.list_batch_tests( type="retell-llm", ) print(response.has_more) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const testCaseJobResponse = await client.tests.getTestRun('test_case_job_id'); console.log(testCaseJobResponse.test_case_definition_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) test_case_job_response = client.tests.get_test_run( "test_case_job_id", ) print(test_case_job_response.test_case_definition_id) /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: listTestRuns 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.tests.listTestRuns('test_case_batch_job_id'); console.log(response.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.tests.list_test_runs( test_case_batch_job_id="test_case_batch_job_id", ) print(response.has_more) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatAgentResponse = await client.chatAgent.create({ response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' }, }); console.log(chatAgentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_agent_response = client.chat_agent.create( response_engine={ "llm_id": "llm_234sdertfsdsfsdf", "type": "retell-llm", }, ) print(chat_agent_response.agent_id) /agent-playground-completion/{agent_id}: post: description: >- Stateless playground completion. Send the full conversation history (same shape as chat completion messages) and receive only the newly generated messages. Nothing is persisted server-side — the caller manages conversation state. operationId: agentPlaygroundCompletion parameters: - name: agent_id in: path required: true schema: type: string description: Unique id of the agent. - name: version in: query required: false schema: $ref: '#/components/schemas/AgentVersionReference' description: Agent version to use. Defaults to latest. requestBody: required: true content: application/json: schema: type: object required: - messages properties: messages: type: array items: $ref: '#/components/schemas/ChatMessageInput' description: >- Full conversation history, same shape as chat completion messages. message_id and created_timestamp are optional — server generates them if omitted. example: - role: user content: Hi, I'd like to check my appointment. - role: agent content: Sure! Could you please provide your name? - role: user content: My name is John Smith. dynamic_variables: type: object additionalProperties: type: string description: Key-value pairs for dynamic variable substitution. example: customer_name: John Smith customer_phone: 444-223-3564 tool_mocks: type: array items: $ref: '#/components/schemas/ToolMock' description: >- Optional mock responses for tools. When provided, the agent uses these instead of executing real tool calls. current_state: type: string description: >- Current state name for retell-llm agents. Used to resume from a specific state. example: greeting current_node_id: type: string description: >- Current node id for conversation-flow agents. Used to resume from a specific node. Must be provided together with component_id when testing components. example: start-node-abc123 component_id: type: string description: >- Conversation flow component id. Required when current_node_id refers to a node within a component. example: component_xyz789 responses: '200': description: Successfully generated playground 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. Same shape as chat completion response messages. Does not include the input messages. current_state: type: string description: Current state name (retell-llm agents). example: greeting current_node_id: type: string description: Current node id (conversation-flow agents). example: node_abc123 dynamic_variables: type: object additionalProperties: type: string description: Updated dynamic variables after this turn. example: customer_name: John Doe call_ended: type: boolean description: Whether the agent ended the conversation. example: false knowledge_base_retrieved_contents: type: array items: type: string description: Knowledge base chunks retrieved for this turn. example: - >- Our business hours are Monday through Friday, 9am to 5pm. '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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.playground.completion('agent_id', { messages: [ { content: "Hi, I'd like to check my appointment.", role: 'user' }, { content: 'Sure! Could you please provide your name?', role: 'agent' }, { content: 'My name is John Smith.', role: 'user' }, ], }); console.log(response.current_node_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.playground.completion( agent_id="agent_id", messages=[{ "content": "Hi, I'd like to check my appointment.", "role": "user", }, { "content": "Sure! Could you please provide your name?", "role": "agent", }, { "content": "My name is John Smith.", "role": "user", }], ) print(response.current_node_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.chat.createChatCompletion({ chat_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', content: 'hi how are you doing?', }); console.log(response.messages); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.chat.create_chat_completion( chat_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", content="hi how are you doing?", ) print(response.messages) /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 chat. agent_version: $ref: '#/components/schemas/AgentVersionReference' 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: type: string 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 created a chat. 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatResponse = await client.chat.create({ agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD' }); console.log(chatResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_response = client.chat.create( agent_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) print(chat_response.agent_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowComponentResponse = await client.conversationFlowComponent.create({ name: 'Customer Information Collector', nodes: [ { id: 'collect_info', instruction: { text: 'Ask the customer for their name and contact information.', type: 'prompt', }, type: 'conversation', }, ], }); console.log(conversationFlowComponentResponse.conversation_flow_component_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_component_response = client.conversation_flow_component.create( name="Customer Information Collector", nodes=[{ "id": "collect_info", "instruction": { "text": "Ask the customer for their name and contact information.", "type": "prompt", }, "type": "conversation", }], ) print(conversation_flow_component_response.conversation_flow_component_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowResponse = await client.conversationFlow.create({ model_choice: { model: 'gpt-4.1', type: 'cascading' }, nodes: [ { id: 'start', instruction: { text: 'Greet the customer and ask how you can help them.', type: 'prompt' }, type: 'conversation', }, ], start_speaker: 'agent', }); console.log(conversationFlowResponse.conversation_flow_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_response = client.conversation_flow.create( model_choice={ "model": "gpt-4.1", "type": "cascading", }, nodes=[{ "id": "start", "instruction": { "text": "Greet the customer and ask how you can help them.", "type": "prompt", }, "type": "conversation", }], start_speaker="agent", ) print(conversation_flow_response.conversation_flow_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const knowledgeBaseResponse = await client.knowledgeBase.create({ knowledge_base_name: 'Sample KB', }); console.log(knowledgeBaseResponse.knowledge_base_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) knowledge_base_response = client.knowledge_base.create( knowledge_base_name="Sample KB", ) print(knowledge_base_response.knowledge_base_id) /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_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. 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. 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, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure 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: >- When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneNumberResponse = await client.phoneNumber.create(); console.log(phoneNumberResponse.last_modification_timestamp); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_number_response = client.phone_number.create() print(phone_number_response.last_modification_timestamp) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const llmResponse = await client.llm.create(); console.log(llmResponse.llm_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) llm_response = client.llm.create() print(llm_response.llm_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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: type: string 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatResponse = await client.chat.createSMSChat({ from_number: '+12137771234', to_number: '+14155551234', }); console.log(chatResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_response = client.chat.create_sms_chat( from_number="+12137771234", to_number="+14155551234", ) print(chat_response.agent_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.agent.delete('oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.agent.delete( "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) /delete-chat/{chat_id}: delete: description: Delete an existing chat operationId: deleteChat parameters: - in: path name: chat_id schema: type: string example: 16b980523634a6dc504898cda492e939 required: true description: Unique id of the chat to be deleted. 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.chat.delete('16b980523634a6dc504898cda492e939'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.chat.delete( "16b980523634a6dc504898cda492e939", ) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.chatAgent.delete('oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.chat_agent.delete( "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.conversationFlowComponent.delete('conversation_flow_component_id'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.conversation_flow_component.delete( "conversation_flow_component_id", ) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.conversationFlow.delete('conversation_flow_id'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.conversation_flow.delete( "conversation_flow_id", ) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const knowledgeBaseResponse = await client.knowledgeBase.deleteSource('source_1234567890', { knowledge_base_id: 'kb_1234567890', }); console.log(knowledgeBaseResponse.knowledge_base_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) knowledge_base_response = client.knowledge_base.delete_source( source_id="source_1234567890", knowledge_base_id="kb_1234567890", ) print(knowledge_base_response.knowledge_base_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.knowledgeBase.delete('kb_1234567890'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.knowledge_base.delete( "kb_1234567890", ) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.phoneNumber.delete('+14157774444'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.phone_number.delete( "+14157774444", ) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.llm.delete('oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.llm.delete( "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.chat.end('16b980523634a6dc504898cda492e939'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.chat.end( "16b980523634a6dc504898cda492e939", ) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const agentResponses = await client.agent.getVersions('16b980523634a6dc504898cda492e939'); console.log(agentResponses); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) agent_responses = client.agent.get_versions( "16b980523634a6dc504898cda492e939", ) print(agent_responses) /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: $ref: '#/components/schemas/AgentVersionReference' 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const agentResponse = await client.agent.retrieve('16b980523634a6dc504898cda492e939'); console.log(agentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) agent_response = client.agent.retrieve( agent_id="16b980523634a6dc504898cda492e939", ) print(agent_response.agent_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatAgentResponses = await client.chatAgent.getVersions('16b980523634a6dc504898cda492e939'); console.log(chatAgentResponses); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_agent_responses = client.chat_agent.get_versions( "16b980523634a6dc504898cda492e939", ) print(chat_agent_responses) /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: $ref: '#/components/schemas/AgentVersionReference' 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatAgentResponse = await client.chatAgent.retrieve('16b980523634a6dc504898cda492e939'); console.log(chatAgentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_agent_response = client.chat_agent.retrieve( agent_id="16b980523634a6dc504898cda492e939", ) print(chat_agent_response.agent_id) /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 a 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatResponse = await client.chat.retrieve('16b980523634a6dc504898cda492e939'); console.log(chatResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_response = client.chat.retrieve( "16b980523634a6dc504898cda492e939", ) print(chat_response.agent_id) /get-concurrency: get: description: Get the current concurrency and concurrency limit of the org operationId: getConcurrency responses: '200': description: Successfully retrieved concurrency information. 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`. reserved_inbound_concurrency: type: integer example: 10 description: >- Number of normal concurrency slots reserved for inbound calls. 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const concurrency = await client.concurrency.retrieve(); console.log(concurrency.base_concurrency); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) concurrency = client.concurrency.retrieve() print(concurrency.base_concurrency) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowComponentResponse = await client.conversationFlowComponent.retrieve( 'conversation_flow_component_id', ); console.log(conversationFlowComponentResponse.conversation_flow_component_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_component_response = client.conversation_flow_component.retrieve( "conversation_flow_component_id", ) print(conversation_flow_component_response.conversation_flow_component_id) /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. Defaults to the 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowResponse = await client.conversationFlow.retrieve('conversation_flow_id'); console.log(conversationFlowResponse.conversation_flow_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_response = client.conversation_flow.retrieve( conversation_flow_id="conversation_flow_id", ) print(conversation_flow_response.conversation_flow_id) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const knowledgeBaseResponse = await client.knowledgeBase.retrieve('kb_1234567890'); console.log(knowledgeBaseResponse.knowledge_base_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) knowledge_base_response = client.knowledge_base.retrieve( "kb_1234567890", ) print(knowledge_base_response.knowledge_base_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const mcpToolDefinitions = await client.mcpTool.getMcpTools('oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', { mcp_id: 'mcp-server-1', }); console.log(mcpToolDefinitions); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) mcp_tool_definitions = client.mcp_tool.get_mcp_tools( agent_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", mcp_id="mcp-server-1", ) print(mcp_tool_definitions) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneNumberResponse = await client.phoneNumber.retrieve('+14157774444'); console.log(phoneNumberResponse.last_modification_timestamp); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_number_response = client.phone_number.retrieve( "+14157774444", ) print(phone_number_response.last_modification_timestamp) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const llmResponse = await client.llm.retrieve('16b980523634a6dc504898cda492e939'); console.log(llmResponse.llm_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) llm_response = client.llm.retrieve( llm_id="16b980523634a6dc504898cda492e939", ) print(llm_response.llm_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const voiceResponse = await client.voice.retrieve('retell-Cimo'); console.log(voiceResponse.provider); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) voice_response = client.voice.retrieve( "retell-Cimo", ) print(voice_response.provider) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const voiceResponse = await client.voice.clone({ files: [fs.createReadStream('path/to/file')], voice_name: 'x', voice_provider: 'elevenlabs', }); console.log(voiceResponse.provider); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) voice_response = client.voice.clone( files=[b"Example data"], voice_name="x", voice_provider="elevenlabs", ) print(voice_response.provider) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const voiceResponse = await client.voice.addResource({ provider_voice_id: 'provider_voice_id', voice_name: 'x', }); console.log(voiceResponse.provider); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) voice_response = client.voice.add_resource( provider_voice_id="provider_voice_id", voice_name="x", ) print(voice_response.provider) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.voice.search({ search_query: 'search_query' }); console.log(response.voices); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.voice.search( search_query="search_query", ) print(response.voices) /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_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. 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. 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, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneNumberResponse = await client.phoneNumber.import({ phone_number: '+14157774444', termination_uri: 'someuri.pstn.twilio.com', }); console.log(phoneNumberResponse.last_modification_timestamp); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_number_response = client.phone_number.import_( phone_number="+14157774444", termination_uri="someuri.pstn.twilio.com", ) print(phone_number_response.last_modification_timestamp) /v2/list-agents: post: description: List unique agents with pagination. operationId: listAgents parameters: - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/SortOrderParam' - $ref: '#/components/parameters/PaginationKeyParam' requestBody: required: false content: application/json: schema: type: object properties: filter_criteria: $ref: '#/components/schemas/AgentListFilter' example: filter_criteria: channel: type: string op: eq value: voice responses: '200': description: Successfully retrieved agents. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponseBase' - type: object properties: items: type: array items: $ref: '#/components/schemas/AgentListItemResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const agents = await client.agent.list({ filter_criteria: { channel: { type: 'string', op: 'eq', value: 'voice', }, }, }); console.log(agents.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) agents = client.agent.list( filter_criteria={ "channel": { "type": "string", "op": "eq", "value": "voice", } }, ) print(agents.has_more) /v3/list-chats: post: description: List chats with unified cursor pagination response. operationId: listChats requestBody: required: false content: application/json: schema: type: object properties: filter_criteria: $ref: '#/components/schemas/ChatFilter' description: Filter criteria for chats to retrieve. sort_order: type: string enum: - ascending - descending default: descending description: >- Sort chats by `start_timestamp` in ascending or descending order. limit: type: integer default: 50 maximum: 1000 description: Maximum number of chats to return. skip: type: integer minimum: 0 default: 0 description: Number of records to skip for pagination. pagination_key: type: string description: Opaque pagination cursor from a previous response. include_total: type: boolean default: false description: >- Whether to include `total` (count of all chats matching `filter_criteria`, ignoring `limit`/`skip`/`pagination_key`) in the response. Defaults to false. Each enabled request triggers an additional aggregate query, so opt in only when the total is needed. not: required: - skip - pagination_key responses: '200': description: Successfully retrieved chats. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponseBase' - type: object properties: items: type: array items: $ref: '#/components/schemas/V3ChatResponse' total: type: integer description: >- Total number of chats matching `filter_criteria`. Only present when `include_total` is true. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chats = await client.chat.list(); console.log(chats.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chats = client.chat.list() print(chats.has_more) /v2/list-conversation-flow-components: get: description: List shared conversation flow components with pagination operationId: listConversationFlowComponents 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowComponents = await client.conversationFlowComponent.list(); console.log(conversationFlowComponents.has_more); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_components = client.conversation_flow_component.list() print(conversation_flow_components.has_more) /v2/list-conversation-flows: get: description: List conversation flows with pagination operationId: listConversationFlows parameters: - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/SortOrderParam' - $ref: '#/components/parameters/PaginationKeyParam' responses: '200': description: Successfully retrieved conversation flows content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponseBase' - type: object properties: items: type: array items: $ref: '#/components/schemas/ConversationFlowResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlows = await client.conversationFlow.list(); console.log(conversationFlows.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flows = client.conversation_flow.list() print(conversation_flows.has_more) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const knowledgeBaseResponses = await client.knowledgeBase.list(); console.log(knowledgeBaseResponses); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) knowledge_base_responses = client.knowledge_base.list() print(knowledge_base_responses) /v2/list-phone-numbers: get: description: List phone numbers with pagination operationId: listPhoneNumbers 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneNumbers = await client.phoneNumber.list(); console.log(phoneNumbers.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_numbers = client.phone_number.list() print(phone_numbers.has_more) /v2/list-retell-llms: get: description: List Retell LLM Response Engines with pagination operationId: listRetellLLM parameters: - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/SortOrderParam' - $ref: '#/components/parameters/PaginationKeyParam' responses: '200': description: Successfully retrieved Retell LLM Response Engines. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponseBase' - type: object properties: items: type: array items: $ref: '#/components/schemas/RetellLLMResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const llms = await client.llm.list(); console.log(llms.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) llms = client.llm.list() print(llms.has_more) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const voiceResponses = await client.voice.list(); console.log(voiceResponses); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) voice_responses = client.voice.list() print(voice_responses) /create-agent-version/{agent_id}: post: description: Create a new draft agent version from a base version. operationId: createAgentVersion parameters: - in: path name: agent_id schema: type: string minLength: 1 example: agent_xxx required: true description: Unique id of the agent. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentVersionRequest' responses: '201': description: Draft version created successfully. content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentResponse' - $ref: '#/components/schemas/ChatAgentResponse' '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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.agent.createVersion('agent_xxx', { base_version: 12 }); console.log(response); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.agent.create_version( agent_id="agent_xxx", base_version=12, ) print(response) /publish-agent-version/{agent_id}: post: description: Publish an existing draft version in place. operationId: publishAgentVersion parameters: - in: path name: agent_id schema: type: string minLength: 1 example: agent_xxx required: true description: Unique id of the agent. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishAgentVersionRequest' responses: '200': description: Agent version published successfully. '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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.agent.publish('agent_xxx', { version: 15 }); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.agent.publish( agent_id="agent_xxx", version=15, ) /delete-agent-version/{agent_id}: delete: description: Delete a specific agent version. operationId: deleteAgentVersion parameters: - in: path name: agent_id schema: type: string minLength: 1 example: agent_xxx required: true description: Unique id of the agent. - in: query name: version schema: type: integer minimum: 0 example: 1 required: true description: Version to delete. responses: '204': description: Version deleted successfully. '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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.agent.deleteVersion('agent_xxx', { version: 1 }); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.agent.delete_version( agent_id="agent_xxx", version=1, ) /rerun-call-analysis/{call_id}: put: description: >- Rerun post-call analysis for a specific call. This operation incurs charges. operationId: rerunCallAnalysis parameters: - in: path name: call_id schema: type: string example: call_119c3f8e47135a29e65947eeb34cf12d required: true description: The call id to rerun analysis for. responses: '201': description: Call analysis rerun successfully. content: application/json: schema: $ref: '#/components/schemas/V2CallResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const callResponse = await client.call.rerunAnalysis('call_119c3f8e47135a29e65947eeb34cf12d'); console.log(callResponse); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) call_response = client.call.rerun_analysis( "call_119c3f8e47135a29e65947eeb34cf12d", ) print(call_response) /rerun-chat-analysis/{chat_id}: put: description: >- Rerun post-chat analysis for a specific chat. This operation incurs charges. operationId: rerunChatAnalysis parameters: - in: path name: chat_id schema: type: string example: chat_16b980523634a6dc504898cda492e939 required: true description: Unique id of the chat to rerun analysis for. responses: '201': description: Chat analysis rerun successfully. content: application/json: schema: $ref: '#/components/schemas/ChatResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatResponse = await client.chat.rerunAnalysis('chat_16b980523634a6dc504898cda492e939'); console.log(chatResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_response = client.chat.rerun_analysis( "chat_16b980523634a6dc504898cda492e939", ) print(chat_response.agent_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const agentResponse = await client.agent.update('16b980523634a6dc504898cda492e939', { agent_name: 'Jarvis', }); console.log(agentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) agent_response = client.agent.update( agent_id="16b980523634a6dc504898cda492e939", agent_name="Jarvis", ) print(agent_response.agent_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatAgentResponse = await client.chatAgent.update('16b980523634a6dc504898cda492e939'); console.log(chatAgentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_agent_response = client.chat_agent.update( agent_id="16b980523634a6dc504898cda492e939", ) print(chat_agent_response.agent_id) /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 variables 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, as key-value pairs. Each attribute must first be defined for your organization in the Retell dashboard (Chat History → Actions → Custom attributes) before it can be set here. The object key must match the id of an existing organization-level custom attribute; keys that do not match a defined attribute are ignored and will not be saved. Values must be a string, number, or boolean. 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatResponse = await client.chat.update('chat_98c1a2157aa0559144d67bb0729', { data_storage_setting: 'everything', metadata: { customer_id: 'cust_123', notes: 'Follow-up required' }, override_dynamic_variables: { additional_discount: '15%' }, }); console.log(chatResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_response = client.chat.update( chat_id="chat_98c1a2157aa0559144d67bb0729", data_storage_setting="everything", metadata={ "customer_id": "cust_123", "notes": "Follow-up required", }, override_dynamic_variables={ "additional_discount": "15%" }, ) print(chat_response.agent_id) /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' '412': $ref: '#/components/responses/PreconditionFailed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowComponentResponse = await client.conversationFlowComponent.update( 'conversation_flow_component_id', ); console.log(conversationFlowComponentResponse.conversation_flow_component_id); - lang: Python source: >- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_component_response = client.conversation_flow_component.update( conversation_flow_component_id="conversation_flow_component_id", ) print(conversation_flow_component_response.conversation_flow_component_id) /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' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const conversationFlowResponse = await client.conversationFlow.update('conversation_flow_id'); console.log(conversationFlowResponse.conversation_flow_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) conversation_flow_response = client.conversation_flow.update( conversation_flow_id="conversation_flow_id", ) print(conversation_flow_response.conversation_flow_id) /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_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. 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. 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. 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. 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, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure other fields specific to that call. nullable: true inbound_sms_webhook_url: type: string example: https://example.com/inbound-sms-webhook description: >- If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, reject the SMS, and configure 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: >- When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. 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_agents: - agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD agent_version: 1 weight: 1 outbound_agents: - agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD agent_version: 1 weight: 1 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneNumberResponse = await client.phoneNumber.update('+14157774444', { inbound_agents: [ { agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', agent_version: 1, weight: 1, }, ], nickname: 'Frontdesk Number', outbound_agents: [ { agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', agent_version: 1, weight: 1, }, ], }); console.log(phoneNumberResponse.last_modification_timestamp); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_number_response = client.phone_number.update( phone_number="+14157774444", inbound_agents=[{ "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "agent_version": 1, "weight": 1, }], nickname="Frontdesk Number", outbound_agents=[{ "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", "agent_version": 1, "weight": 1, }], ) print(phone_number_response.last_modification_timestamp) /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' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const llmResponse = await client.llm.update('16b980523634a6dc504898cda492e939', { begin_message: 'Hey I am a virtual assistant calling from Retell Hospital.', }); console.log(llmResponse.llm_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) llm_response = client.llm.update( llm_id="16b980523634a6dc504898cda492e939", begin_message="Hey I am a virtual assistant calling from Retell Hospital.", ) print(llm_response.llm_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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: type: string 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneCallResponse = await client.call.createPhoneCall({ from_number: '+14157774444', to_number: '+12137774445', }); console.log(phoneCallResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_call_response = client.call.create_phone_call( from_number="+14157774444", to_number="+12137774445", ) print(phone_call_response.agent_id) /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: $ref: '#/components/schemas/AgentVersionReference' 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: type: string 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const webCallResponse = await client.call.createWebCall({ agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', }); console.log(webCallResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) web_call_response = client.call.create_web_call( agent_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) print(web_call_response.agent_id) /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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.call.delete('119c3f8e47135a29e65947eeb34cf12d'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.call.delete( "119c3f8e47135a29e65947eeb34cf12d", ) /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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const callResponse = await client.call.retrieve('119c3f8e47135a29e65947eeb34cf12d'); console.log(callResponse); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) call_response = client.call.retrieve( "119c3f8e47135a29e65947eeb34cf12d", ) print(call_response) /v3/list-calls: post: description: List calls with unified cursor pagination response. operationId: listCalls requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/V3ListCallsRequest' responses: '200': description: Successfully retrieved calls. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponseBase' - type: object properties: items: type: array items: $ref: '#/components/schemas/V3CallResponse' total: type: integer description: >- Total number of calls matching `filter_criteria`. Only present when `include_total` is true. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const calls = await client.call.list(); console.log(calls.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) calls = client.call.list() print(calls.has_more) /v2/list-export-requests: get: description: List export requests with pagination operationId: listExportRequests 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const exportRequests = await client.exportRequest.list(); console.log(exportRequests.has_more); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) export_requests = client.export_request.list() print(export_requests.has_more) /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: $ref: '#/components/schemas/AgentVersionReference' 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: type: string 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' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const phoneCallResponse = await client.call.registerPhoneCall({ agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', }); console.log(phoneCallResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) phone_call_response = client.call.register_phone_call( agent_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD", ) print(phone_call_response.agent_id) /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 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, as key-value pairs. Each attribute must first be defined for your organization in the Retell dashboard (Call History → Actions → Custom attributes) before it can be set here. The object key must match the id of an existing organization-level custom attribute; keys that do not match a defined attribute are ignored and will not be saved. Values must be a string, number, or boolean. 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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const callResponse = await client.call.update('call_a4441234567890777c4a4a123e6', { data_storage_setting: 'everything_except_pii', metadata: { customer_id: 'cust_123', notes: 'Follow-up required' }, }); console.log(callResponse); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) call_response = client.call.update( call_id="call_a4441234567890777c4a4a123e6", data_storage_setting="everything_except_pii", metadata={ "customer_id": "cust_123", "notes": "Follow-up required", }, ) print(call_response) /v2/update-live-call/{call_id}: patch: description: >- Update an ongoing call at runtime. Supports overriding dynamic variables, metadata, and the data storage setting on the running call, and controlling the live agent (inject context, trigger a response). These overrides take effect immediately on the live call; metadata and data storage setting changes are also persisted to the call record. To update a call that is no longer ongoing, use /v2/update-call/{call_id}. operationId: updateLiveCall parameters: - in: path name: call_id schema: type: string example: call_a4441234567890777c4a4a123e6 required: true description: The call id of the ongoing call to be updated. requestBody: required: true content: application/json: schema: type: object properties: fields_to_override: type: object description: > Call fields to override on the running call. Each field is applied to the live call immediately; omitted fields are left unchanged. properties: override_dynamic_variables: type: object additionalProperties: type: string example: additional_discount: 15% description: >- Override dynamic variables 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 metadata: type: object description: >- An arbitrary object for storage purpose only. Overrides the metadata on the call. 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 additionalProperties: false call_control: type: object description: > Live agent control. At least one of `additional_context` or `trigger_response` should be supplied; an empty object is a no-op. properties: trigger_response: type: boolean description: > Only `true` has an effect. When set, if the agent is currently speaking the response is interrupted and a new one is generated. If the agent has already finished speaking and is waiting silently for the user, the agent is nudged to produce another response. If the user is currently speaking, this field is a no-op so the agent does not talk over them. This field respects the agent's `interruption_sensitivity`: when sensitivity is `0` the agent's current speech is treated as uninterruptible, so `trigger_response` is a no-op while the agent is speaking. Omitting or setting `false` leaves the call untouched. additional_context: type: string minLength: 1 description: > Free-form text appended to the call transcript with role "injected" and injected into the next agent response context. Must be non-empty. additionalProperties: false additionalProperties: false example: fields_to_override: override_dynamic_variables: additional_discount: 15% call_control: additional_context: Customer just opened a support ticket about billing. trigger_response: true responses: '200': description: Live call updated successfully content: application/json: schema: type: object required: - success properties: success: type: boolean example: true '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' x-codeSamples: - lang: JavaScript source: >- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const response = await client.call.updateLive('call_a4441234567890777c4a4a123e6', { call_control: { additional_context: 'Customer just opened a support ticket about billing.', trigger_response: true, }, fields_to_override: { override_dynamic_variables: { additional_discount: '15%' } }, }); console.log(response.success); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) response = client.call.update_live( call_id="call_a4441234567890777c4a4a123e6", call_control={ "additional_context": "Customer just opened a support ticket about billing.", "trigger_response": True, }, fields_to_override={ "override_dynamic_variables": { "additional_discount": "15%" } }, ) print(response.success) /v2/stop-call/{call_id}: post: description: Stop an ongoing call. operationId: stopCall parameters: - in: path name: call_id schema: type: string example: call_a4441234567890777c4a4a123e6 required: true description: The call id of the ongoing call to be stopped. responses: '204': description: Call stopped successfully '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableContent' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); await client.call.stop('call_a4441234567890777c4a4a123e6'); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) client.call.stop( "call_a4441234567890777c4a4a123e6", )