Agents
Create Agent
Create an agent with empty dev, staging, and production environments.
POST
/
v2
/
agents
Create Agent
curl --request POST \
--url https://api.bland.ai/v2/agents \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents"
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', 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",
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"
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")
.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")
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": {
"agent": {
"id": "2f2750b7-fed3-4798-992a-421ccf8b93b2",
"org_id": "45794f66-94ca-44a2-9248-202c5ff22717",
"name": "Front desk",
"created_by": "bd8ae00b-c51d-4364-b1b3-245ad579c44a",
"created_at": "2026-09-10T22:59:51.569Z",
"updated_at": "2026-09-10T22:59:51.569Z",
"deleted_at": null
},
"environments": [
{
"id": "7a043546-b896-4680-80e4-5eb9cbde6977",
"env_type": "dev",
"current_version_id": null
},
{
"id": "ab412aa2-8827-4e12-ad45-9a964c2c8690",
"env_type": "staging",
"current_version_id": null
},
{
"id": "1595512d-ea18-4692-a40b-6c90932396b4",
"env_type": "production",
"current_version_id": null
}
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "name must be a non-empty string"
}
]
}
Overview
Creates an agent and its three environments (dev, staging, production) in one step. The environments start unpinned; save a version with Create Agent Version and promote it to pin one. To build an agent from the dashboard instead, see Build your first agent.
Requires an admin, owner, operator, or prompter role.
Headers
Body Parameters
Display name for the agent. Must be non-empty after trimming whitespace. Returns
400 INVALID_NAME otherwise.Response
Returns201 on success.
The new agent.
Show agent object
Show agent object
ID of the user who created the agent. With an API key, this is the user the key belongs to.
null when no user was recorded.{
"data": {
"agent": {
"id": "2f2750b7-fed3-4798-992a-421ccf8b93b2",
"org_id": "45794f66-94ca-44a2-9248-202c5ff22717",
"name": "Front desk",
"created_by": "bd8ae00b-c51d-4364-b1b3-245ad579c44a",
"created_at": "2026-09-10T22:59:51.569Z",
"updated_at": "2026-09-10T22:59:51.569Z",
"deleted_at": null
},
"environments": [
{
"id": "7a043546-b896-4680-80e4-5eb9cbde6977",
"env_type": "dev",
"current_version_id": null
},
{
"id": "ab412aa2-8827-4e12-ad45-9a964c2c8690",
"env_type": "staging",
"current_version_id": null
},
{
"id": "1595512d-ea18-4692-a40b-6c90932396b4",
"env_type": "production",
"current_version_id": null
}
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "name must be a non-empty string"
}
]
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
Create Agent
curl --request POST \
--url https://api.bland.ai/v2/agents \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents"
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', 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",
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"
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")
.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")
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": {
"agent": {
"id": "2f2750b7-fed3-4798-992a-421ccf8b93b2",
"org_id": "45794f66-94ca-44a2-9248-202c5ff22717",
"name": "Front desk",
"created_by": "bd8ae00b-c51d-4364-b1b3-245ad579c44a",
"created_at": "2026-09-10T22:59:51.569Z",
"updated_at": "2026-09-10T22:59:51.569Z",
"deleted_at": null
},
"environments": [
{
"id": "7a043546-b896-4680-80e4-5eb9cbde6977",
"env_type": "dev",
"current_version_id": null
},
{
"id": "ab412aa2-8827-4e12-ad45-9a964c2c8690",
"env_type": "staging",
"current_version_id": null
},
{
"id": "1595512d-ea18-4692-a40b-6c90932396b4",
"env_type": "production",
"current_version_id": null
}
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_NAME",
"message": "name must be a non-empty string"
}
]
}