Create Agent Branch
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/branches \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/branches"
payload = { "name": "<string>" }
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>'})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/branches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/branches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/branches"
payload := strings.NewReader("{\n \"name\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/branches")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/branches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "08aacbb3-6f83-4542-a7c0-1fd07b5b3d47",
"agent_id": "f4f9fe3f-a996-49a6-934d-6b78b144d43b",
"name": "billing-questions",
"base_version_id": "0b6b3dba-0c8c-4ee2-a992-4a7bc2f35e25",
"created_by": "0d5eee46-6f39-462b-b347-79ff13cf3cf2",
"created_at": "2026-09-10T17:42:18.093Z",
"behind": false
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "\"staging\" is reserved for version selectors"
}
]
}
{
"data": null,
"errors": [
{
"error": "BRANCH_EXISTS",
"message": "An open branch with this name already exists"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Branches
Create Agent Branch
Create a branch off the agent’s dev head.
POST
/
v2
/
agents
/
{agent_id}
/
branches
Create Agent Branch
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/branches \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/branches"
payload = { "name": "<string>" }
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>'})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/branches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/branches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/branches"
payload := strings.NewReader("{\n \"name\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/branches")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/branches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "08aacbb3-6f83-4542-a7c0-1fd07b5b3d47",
"agent_id": "f4f9fe3f-a996-49a6-934d-6b78b144d43b",
"name": "billing-questions",
"base_version_id": "0b6b3dba-0c8c-4ee2-a992-4a7bc2f35e25",
"created_by": "0d5eee46-6f39-462b-b347-79ff13cf3cf2",
"created_at": "2026-09-10T17:42:18.093Z",
"behind": false
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "\"staging\" is reserved for version selectors"
}
]
}
{
"data": null,
"errors": [
{
"error": "BRANCH_EXISTS",
"message": "An open branch with this name already exists"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Overview
Cuts a new branch from the agent’s newest dev version. Versions saved to the branch stay off the dev timeline until you land them with Merge Agent Branch. Use List Agent Branches to see what is open. Requires an admin, owner, operator, or prompter role.Headers
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier.
Body Parameters
string
required
The branch name. Trimmed, then must be 1 to 64 characters using only letters, numbers, dots, underscores, and dashes. The names
dev, latest, staging, and production (any casing) and anything shaped like a version number (for example 1.2.0) are reserved for version selectors. Any of these problems returns 400 INVALID_NAME with a message naming the rule. Returns 409 BRANCH_EXISTS when an open branch already has this name; names of merged or deleted branches can be reused.Response
Returns201 on success.
object
The new branch.
Show branch object
Show branch object
string
Unique identifier for the branch. Pass it as
{branch_id} on the other branch endpoints.string
The agent the branch belongs to.
string
The trimmed branch name.
string | null
The dev version the branch was cut from.
null when the agent has no saved versions yet.string | null
ID of the user who created the branch, or
null when created with an org-level key.string
ISO 8601 timestamp of creation.
boolean
Always
false on a newly created branch.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"id": "08aacbb3-6f83-4542-a7c0-1fd07b5b3d47",
"agent_id": "f4f9fe3f-a996-49a6-934d-6b78b144d43b",
"name": "billing-questions",
"base_version_id": "0b6b3dba-0c8c-4ee2-a992-4a7bc2f35e25",
"created_by": "0d5eee46-6f39-462b-b347-79ff13cf3cf2",
"created_at": "2026-09-10T17:42:18.093Z",
"behind": false
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "\"staging\" is reserved for version selectors"
}
]
}
{
"data": null,
"errors": [
{
"error": "BRANCH_EXISTS",
"message": "An open branch with this name already exists"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?