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"
}
]
}
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
string
required
Your API key for authentication.
Body Parameters
string
required
Display name for the agent. Must be non-empty after trimming whitespace. Returns
400 INVALID_NAME otherwise.Response
Returns201 on success.
object
The new agent.
Show agent object
Show agent object
string
Unique identifier for the agent.
string
The organization that owns the agent.
string
The agent’s display name.
string | null
ID of the user who created the agent, or
null when created with an org-level key.string
ISO 8601 timestamp of creation.
string
ISO 8601 timestamp of the last update.
null
Always
null on a live agent.array
null | array
null on success, or a list of error objects if the request failed.{
"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?