The List Conversation Flows API from Retell AI — 2 operation(s) for list conversation flows.
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice List Conversation Flows 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 Flows
paths:
/v2/list-conversation-flows:
get:
description: List conversation flows with pagination
operationId: listConversationFlowsV2
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'
tags:
- List Conversation Flows
/list-conversation-flows:
get:
description: List all conversation flows that can be attached to an agent.
operationId: listConversationFlows
deprecated: true
parameters:
- in: query
name: limit
description: Limit the number of conversation flows returned. Default 1000, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.
schema:
type: integer
default: 1000
maximum: 1000
- in: query
name: pagination_key
description: The pagination key to continue fetching the next page of conversation flows. Pagination key is represented by a conversation flow id here, and it's exclusive (not included in the fetched conversation flows). The last conversation flow id from the list conversation flows is usually used as pagination key here. If not set, will start from the beginning.
schema:
type: string
- in: query
name: pagination_key_version
schema:
type: integer
description: Specifies the version of the conversation flow associated with the pagination_key. When paginating, both the pagination_key and its version must be provided to ensure consistent ordering and to fetch the next page correctly.
responses:
'200':
description: Successfully retrieved conversation flows
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConversationFlowResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- List Conversation Flows
components:
responses:
Forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Forbidden
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.
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.
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.
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.
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
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-list-conversation-flows-api-openapi.yml