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
Path Parameters
Body Parameters
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.
The new branch.
Show branch object
Show branch object
The dev version the branch was cut from.
null when the agent has no saved versions yet.ID of the user who created the branch. With an API key, this is the user the key belongs to.
null when no user was recorded.{
"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?
⌘I
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"
}
]
}