POST
/
create-conversation-flow
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const conversationFlowResponse = await client.conversationFlow.create({
  model_choice: { model: 'gpt-5', 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);
{
  "global_prompt": "You are a helpful customer service agent.",
  "tools": [
    {
      "type": "custom",
      "name": "get_customer_info",
      "description": "Get customer information from database",
      "tool_id": "tool_001",
      "url": "https://api.example.com/customer",
      "method": "GET"
    }
  ],
  "start_node_id": "start",
  "model_temperature": 0.7,
  "tool_call_strict_mode": true,
  "default_dynamic_variables": {
    "company_name": "Retell Inc",
    "support_hours": "9 AM - 5 PM"
  },
  "knowledge_base_ids": [
    "kb_001",
    "kb_002"
  ],
  "kb_config": {
    "top_k": 3,
    "filter_score": 0.6
  },
  "begin_tag_display_position": {
    "x": 100,
    "y": 200
  },
  "mcps": [
    {
      "name": "<string>",
      "url": "<string>",
      "headers": {
        "Authorization": "Bearer 1234567890"
      },
      "query_params": {
        "index": "1",
        "key": "value"
      },
      "timeout_ms": 123
    }
  ],
  "start_speaker": "agent",
  "model_choice": {
    "type": "cascading",
    "model": "gpt-5",
    "high_priority": true
  },
  "nodes": [
    {
      "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"
        }
      ]
    }
  ],
  "conversation_flow_id": "<string>",
  "version": 123
}

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
​
start_speaker
enum<string>
required

Who starts the conversation - user or agent.

Available options:
user,
agent
Example:

"agent"

​
model_choice
object
required

The model choice for the conversation flow.

​
nodes
object[]
required

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"
      }
    ]
  }
]
​
global_prompt
string | null

Global prompt used in every node of the conversation flow.

Example:

"You are a helpful customer service agent."

​
tools
object[] | null

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"
  }
]
​
start_node_id
string | null

ID of the start node in the conversation flow.

Example:

"start"

​
model_temperature
number | null

Controls the randomness of the model's responses. Lower values make responses more deterministic.

Required range: 0 <= x <= 1
Example:

0.7

​
tool_call_strict_mode
boolean | null

Whether to use strict mode for tool calls. Only applicable when using structured output models.

Example:

true

​
default_dynamic_variables
object | null

Default dynamic variables that can be referenced throughout the conversation flow.

Example:
{
  "company_name": "Retell Inc",
  "support_hours": "9 AM - 5 PM"
}
​
knowledge_base_ids
string[] | null

Knowledge base IDs for RAG (Retrieval-Augmented Generation).

Example:
["kb_001", "kb_002"]
​
kb_config
object

Knowledge base configuration for RAG retrieval.

​
begin_tag_display_position
object | null

Display position for the begin tag in the frontend.

​
mcps
object[] | null

A list of MCP server configurations to use for this conversation flow.

Response

Successfully created a conversation flow

​
conversation_flow_id
string
required

Unique identifier for the conversation flow

​
version
integer
required

Version number of the conversation flow

​
global_prompt
string | null

Global prompt used in every node of the conversation flow.

Example:

"You are a helpful customer service agent."

​
tools
object[] | null

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"
  }
]
​
start_node_id
string | null

ID of the start node in the conversation flow.

Example:

"start"

​
model_temperature
number | null

Controls the randomness of the model's responses. Lower values make responses more deterministic.

Required range: 0 <= x <= 1
Example:

0.7

​
tool_call_strict_mode
boolean | null

Whether to use strict mode for tool calls. Only applicable when using structured output models.

Example:

true

​
default_dynamic_variables
object | null

Default dynamic variables that can be referenced throughout the conversation flow.

Example:
{
  "company_name": "Retell Inc",
  "support_hours": "9 AM - 5 PM"
}
​
knowledge_base_ids
string[] | null

Knowledge base IDs for RAG (Retrieval-Augmented Generation).

Example:
["kb_001", "kb_002"]
​
kb_config
object

Knowledge base configuration for RAG retrieval.

​
begin_tag_display_position
object | null

Display position for the begin tag in the frontend.

​
mcps
object[] | null

A list of MCP server configurations to use for this conversation flow.

​
start_speaker
enum<string>

Who starts the conversation - user or agent.

Available options:
user,
agent
Example:

"agent"

​
model_choice
object

The model choice for the conversation flow.

​
nodes
object[]

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"
      }
    ]
  }
]