curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/branches' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "parent_version_id": "parent-version-id",
  "name": "example-name",
  "description": "example-description",
  "conversation_config": {},
  "platform_settings": {},
  "workflow": {
    "edges": {
      "entry_to_tool_a": {
        "forward_condition": {
          "condition": "Tool A condition"
        },
        "source": "entry_node",
        "target": "tool_node_a"
      },
      "start_to_entry": {
        "forward_condition": {},
        "source": "start_node",
        "target": "entry_node"
      },
      "tool_a_to_failure": {
        "forward_condition": {
          "successful": false
        },
        "source": "tool_node_a",
        "target": "failure_node"
      },
      "tool_a_to_tool_b": {
        "forward_condition": {
          "successful": true
        },
        "source": "tool_node_a",
        "target": "tool_node_b"
      },
      "tool_b_to_agent_transfer": {
        "forward_condition": {},
        "source": "tool_node_b",
        "target": "success_transfer"
      },
      "tool_b_to_conversation": {
        "forward_condition": {
          "condition": "Conversation condition"
        },
        "source": "tool_node_b",
        "target": "success_conversation"
      },
      "tool_b_to_end": {
        "forward_condition": {
          "condition": "End condition"
        },
        "source": "tool_node_b",
        "target": "success_end"
      },
      "tool_b_to_phone": {
        "forward_condition": {
          "expression": {
            "children": [
              {
                "name": "force_phone_transfer"
              },
              {
                "prompt": "Phone condition",
                "value_schema": {
                  "description": "Phone condition",
                  "type": "boolean"
                }
              },
              {
                "left": {
                  "name": "mode"
                },
                "right": {
                  "value": "dev"
                }
              }
            ]
          }
        },
        "source": "tool_node_b",
        "target": "success_phone"
      }
    },
    "nodes": {
      "entry_node": {
        "conversation_config": {},
        "edge_order": [
          "entry_to_tool_a"
        ],
        "label": "Entry"
      },
      "failure_node": {
        "conversation_config": {},
        "label": "Failure"
      },
      "start_node": {
        "edge_order": [
          "start_to_entry"
        ]
      },
      "success_conversation": {
        "conversation_config": {},
        "label": "Success A"
      },
      "success_end": {},
      "success_phone": {
        "transfer_destination": {
          "phone_number": "+1234567890"
        }
      },
      "success_transfer": {
        "agent_id": "success_transfer_agent"
      },
      "tool_node_a": {
        "edge_order": [
          "tool_a_to_failure",
          "tool_a_to_tool_b"
        ],
        "tools": [
          {
            "tool_id": "tool_a"
          },
          {
            "tool_id": "tool_b"
          }
        ]
      },
      "tool_node_b": {
        "edge_order": [
          "tool_b_to_conversation",
          "tool_b_to_end",
          "tool_b_to_phone",
          "tool_b_to_agent_transfer"
        ],
        "tools": [
          {
            "tool_id": "tool_a"
          }
        ]
      }
    }
  },
  "include_draft": false
}'

# POST /v1/convai/agents/{agent_id}/branches (ElevenLabs API)
Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20

> Create A New Branch

## Critical Gotchas
* Authentication uses the non-standard `xi-api-key` header, not `Authorization: Bearer`. Sending a Bearer token returns HTTP 401.
* Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (`--output speech.mp3`) rather than parsing it.

## cURL
curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/branches' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"parent_version_id":"parent-version-id","name":"example-name","description":"example-description"}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| agent_id | path | string | Yes | The id of an agent. This is returned... |
| parent_version_id | body | string | Yes | ID of the version to branch from |
| name | body | string | Yes | Name of the branch. It is unique with... |
Other params: description, conversation_config, platform_settings, workflow, include_draft

## Response (200 OK)
{"created_branch_id":"string","created_version_id":"string"}

---
Need an API key? Get one at https://elevenlabs.io/app/sign-up

POST

POST /v1/convai/agents/{agent_id}/branches — ElevenLabs API

ElevenLabs API

Create A New Branch

Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 228 tokens · Vary: Accept

Critical gotchas

Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.

Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.

cURL

curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/branches' \  -H "xi-api-key: $ELEVENLABS_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "parent_version_id": "parent-version-id",  "name": "example-name",  "description": "example-description",  "conversation_config": {},  "platform_settings": {},  "workflow": {    "edges": {      "entry_to_tool_a": {        "forward_condition": {          "condition": "Tool A condition"        },        "source": "entry_node",        "target": "tool_node_a"      },      "start_to_entry": {        "forward_condition": {},        "source": "start_node",        "target": "entry_node"      },      "tool_a_to_failure": {        "forward_condition": {          "successful": false        },        "source": "tool_node_a",        "target": "failure_node"      },      "tool_a_to_tool_b": {        "forward_condition": {          "successful": true        },        "source": "tool_node_a",        "target": "tool_node_b"      },      "tool_b_to_agent_transfer": {        "forward_condition": {},        "source": "tool_node_b",        "target": "success_transfer"      },      "tool_b_to_conversation": {        "forward_condition": {          "condition": "Conversation condition"        },        "source": "tool_node_b",        "target": "success_conversation"      },      "tool_b_to_end": {        "forward_condition": {          "condition": "End condition"        },        "source": "tool_node_b",        "target": "success_end"      },      "tool_b_to_phone": {        "forward_condition": {          "expression": {            "children": [              {                "name": "force_phone_transfer"              },              {                "prompt": "Phone condition",                "value_schema": {                  "description": "Phone condition",                  "type": "boolean"                }              },              {                "left": {                  "name": "mode"                },                "right": {                  "value": "dev"                }              }            ]          }        },        "source": "tool_node_b",        "target": "success_phone"      }    },    "nodes": {      "entry_node": {        "conversation_config": {},        "edge_order": [          "entry_to_tool_a"        ],        "label": "Entry"      },      "failure_node": {        "conversation_config": {},        "label": "Failure"      },      "start_node": {        "edge_order": [          "start_to_entry"        ]      },      "success_conversation": {        "conversation_config": {},        "label": "Success A"      },      "success_end": {},      "success_phone": {        "transfer_destination": {          "phone_number": "+1234567890"        }      },      "success_transfer": {        "agent_id": "success_transfer_agent"      },      "tool_node_a": {        "edge_order": [          "tool_a_to_failure",          "tool_a_to_tool_b"        ],        "tools": [          {            "tool_id": "tool_a"          },          {            "tool_id": "tool_b"          }        ]      },      "tool_node_b": {        "edge_order": [          "tool_b_to_conversation",          "tool_b_to_end",          "tool_b_to_phone",          "tool_b_to_agent_transfer"        ],        "tools": [          {            "tool_id": "tool_a"          }        ]      }    }  },  "include_draft": false}'

Parameters

Name	In	Type	Required	Description
agent_id	path	string	Yes	The id of an agent. This is returned on agent creation.
parent_version_id	body	string	Yes	ID of the version to branch from
name	body	string	Yes	Name of the branch. It is unique within the agent.
description	body	string	Yes	Description for the branch
conversation_config	body	object	No	Changes to apply to conversation config
platform_settings	body	object	No	Changes to apply to platform settings
workflow	body	object	No	Updated workflow definition
include_draft	body	boolean	No	When true, the new branch uses the caller's draft procedure set instead of the branch tip. Requires parent_version_id to be the branch tip.

Response 200 OK

{
  "created_branch_id": "string",
  "created_version_id": "string"
}

Get a free ElevenLabs API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.