The List Conversation Flow Components API from Retell AI — 2 operation(s) for list conversation flow components.
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice List Conversation Flow Components API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: List Conversation Flow Components
paths:
/v2/list-conversation-flow-components:
get:
description: List shared conversation flow components with pagination
operationId: listConversationFlowComponentsV2
parameters:
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/SortOrderParam'
- $ref: '#/components/parameters/PaginationKeyParam'
responses:
'200':
description: Successfully listed conversation flow components
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponseBase'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ConversationFlowComponentResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- List Conversation Flow Components
/list-conversation-flow-components:
get:
description: List shared conversation flow components
operationId: listConversationFlowComponents
deprecated: true
responses:
'200':
description: Successfully listed conversation flow components
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConversationFlowComponentResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- List Conversation Flow Components
components:
schemas:
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'
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
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.
AgentSwapWebhookSetting:
type: string
enum:
- both_agents
- only_destination_agent
- only_source_agent
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.
ModelChoice:
oneOf:
- $ref: '#/components/schemas/ModelChoiceCascading'
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
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
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
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
ExtractDynamicVariableTool:
type: object
properties:
type:
type: string
enum:
- extract_dynamic_variable
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
description:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
variables:
type: array
items:
$ref: '#/components/schemas/AnalysisData'
description: The variables to be extracted.
required:
- type
- name
- variables
- description
SmsContent:
oneOf:
- $ref: '#/components/schemas/SmsContentPredefined'
- $ref: '#/components/schemas/SmsContentInferred'
- $ref: '#/components/schemas/SmsContentTemplate'
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
CustomTool:
type: object
properties:
type:
type: string
enum:
- custom
name:
type: string
description: Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
url:
type: string
description: Describes what the tool does, sometimes can also include information about when to call the tool.
description:
type: string
description: Describes what this tool does and when to call this tool.
method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
description: Method to use for the request, default to POST.
headers:
type: object
additionalProperties:
type: string
example:
Authorization: Bearer 1234567890
description: Headers to add to the request.
query_params:
type: object
additionalProperties:
type: string
example:
page: '1'
sort: asc
description: Query parameters to append to the request URL.
parameters:
$ref: '#/components/schemas/ToolParameter'
response_variables:
type: object
additionalProperties:
type: string
example:
user_name: data.user.name
description: A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use.
speak_during_execution:
type: boolean
description: Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive.
speak_after_execution:
type: boolean
description: Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call.
execution_message_description:
type: string
description: The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.".
execution_message_type:
type: string
enum:
- prompt
- static_text
description: Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt".
timeout_ms:
type: integer
description: The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min).
args_at_root:
type: boolean
description: If set to true, the parameters will be passed as root level JSON object instead of nested under "args".
enable_typing_sound:
type: boolean
description: If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call.
required:
- type
- name
- url
SubagentNode:
allOf:
- $ref: '#/components/schemas/NodeBase'
- $ref: '#/components/schemas/AgentOverrideConfig'
- type: object
required:
- type
- instruction
properties:
type:
type: string
enum:
- subagent
description: Type of the node
instruction:
$ref: '#/components/schemas/NodeInstructionPrompt'
skip_response_edge:
$ref: '#/components/schemas/SkipResponseEdge'
always_edge:
$ref: '#/components/schemas/AlwaysEdge'
edges:
type: array
items:
$ref: '#/components/schemas/NodeEdge'
finetune_conversation_examples:
type: array
items:
$ref: '#/components/schemas/NodeFinetuneConversationExample'
finetune_transition_examples:
type: array
items:
$ref: '#/components/schemas/NodeFinetuneTransitionExample'
knowledge_base_ids:
type: array
items:
type: string
description: Knowledge base IDs for RAG (Retrieval-Augmented Generation).
nullable: true
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
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.
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.
ConversationFlowComponent:
type: object
properties:
name:
type: string
description: Name of the component
example: Customer Information Collector
tools:
type: array
items:
$ref: '#/components/schemas/NodeTool'
description: Tools available within the component
example:
- type: custom
name: get_customer_info
description: Get customer information from database
tool_id: tool_001
url: https://api.example.com/customer
method: GET
nullable: true
mcps:
type: array
items:
$ref: '#/components/schemas/MCP'
description: A list of MCP server configurations to use for this component
nullable: true
nodes:
type: array
items:
$ref: '#/components/schemas/ConversationFlowNode'
description: Nodes that make up the component
example:
- id: collect_info
type: conversation
instruction:
type: prompt
text: Ask the customer for their name and contact information.
start_node_id:
type: string
description: ID of the starting node
example: collect_info
nullable: true
begin_tag_display_position:
type: object
properties:
x:
type: number
example: 100
y:
type: number
example: 200
description: Display position for the begin tag in the frontend
nullable: true
notes:
type: array
items:
$ref: '#/components/schemas/Note'
description: Visual annotations displayed on the flow canvas.
nullable: true
PromptCondition:
type: object
required:
- type
- prompt
properties:
type:
type: string
enum:
- prompt
prompt:
type: string
description: Prompt condition text
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.
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
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'
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
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'
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
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.
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
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
- claude-4.5-sonnet
- claude-4.6-sonnet
- claude-4.5-haiku
- gemini-2.5-flash-lite
- gemini-3.0-flash
- gemini-3.1-flash-lite
description: Available LLM models for agents.
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.
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'
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
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
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.
SmsContentPredefined:
type: object
properties:
type:
type: string
enum:
- predefined
content:
type: string
description: The static message to be sent in the SMS. Can contain dynamic variables.
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.
AgentVersionReference:
oneOf:
- type: integer
minimum: 0
example: 1
- type: string
minLength: 1
maxLength: 20
pattern: ^[a-z0-9_-]+$
example: prod
description: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). When
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-list-conversation-flow-components-api-openapi.yml