Create Test Scenario
curl --request POST \
--url https://api.bland.ai/v1/agent-testing/scenarios \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"pathway_id": "<string>",
"persona_id": "<string>",
"name": "<string>",
"description": "<string>",
"category": "<string>",
"scenario_type": "<string>",
"tester_persona_prompt": "<string>",
"tester_persona_name": "<string>",
"max_turns": 123,
"request_data": {},
"start_node_id": "<string>",
"bland_tone_enabled": true,
"is_required_for_promotion": true,
"input_messages": [
{}
],
"advanced_instructions": "<string>",
"metadata": {},
"assertions": [
{
"type": "<string>",
"config": {},
"name": "<string>",
"is_required": true,
"weight": 123,
"order": 123
}
]
}
'import requests
url = "https://api.bland.ai/v1/agent-testing/scenarios"
payload = {
"pathway_id": "<string>",
"persona_id": "<string>",
"name": "<string>",
"description": "<string>",
"category": "<string>",
"scenario_type": "<string>",
"tester_persona_prompt": "<string>",
"tester_persona_name": "<string>",
"max_turns": 123,
"request_data": {},
"start_node_id": "<string>",
"bland_tone_enabled": True,
"is_required_for_promotion": True,
"input_messages": [{}],
"advanced_instructions": "<string>",
"metadata": {},
"assertions": [
{
"type": "<string>",
"config": {},
"name": "<string>",
"is_required": True,
"weight": 123,
"order": 123
}
]
}
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({
pathway_id: '<string>',
persona_id: '<string>',
name: '<string>',
description: '<string>',
category: '<string>',
scenario_type: '<string>',
tester_persona_prompt: '<string>',
tester_persona_name: '<string>',
max_turns: 123,
request_data: {},
start_node_id: '<string>',
bland_tone_enabled: true,
is_required_for_promotion: true,
input_messages: [{}],
advanced_instructions: '<string>',
metadata: {},
assertions: [
{
type: '<string>',
config: {},
name: '<string>',
is_required: true,
weight: 123,
order: 123
}
]
})
};
fetch('https://api.bland.ai/v1/agent-testing/scenarios', 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/v1/agent-testing/scenarios",
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([
'pathway_id' => '<string>',
'persona_id' => '<string>',
'name' => '<string>',
'description' => '<string>',
'category' => '<string>',
'scenario_type' => '<string>',
'tester_persona_prompt' => '<string>',
'tester_persona_name' => '<string>',
'max_turns' => 123,
'request_data' => [
],
'start_node_id' => '<string>',
'bland_tone_enabled' => true,
'is_required_for_promotion' => true,
'input_messages' => [
[
]
],
'advanced_instructions' => '<string>',
'metadata' => [
],
'assertions' => [
[
'type' => '<string>',
'config' => [
],
'name' => '<string>',
'is_required' => true,
'weight' => 123,
'order' => 123
]
]
]),
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/v1/agent-testing/scenarios"
payload := strings.NewReader("{\n \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\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/v1/agent-testing/scenarios")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/agent-testing/scenarios")
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 \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
"pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd",
"persona_id": null,
"name": "Angry Caller Test",
"description": "Tests the agent's ability to de-escalate an angry caller",
"category": "ANGRY_CALLER",
"scenario_type": "AGENT",
"tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.",
"tester_persona_name": "Frustrated Customer",
"max_turns": 15,
"request_data": null,
"start_node_id": null,
"bland_tone_enabled": true,
"is_required_for_promotion": false,
"enabled": true,
"input_messages": null,
"advanced_instructions": null,
"metadata": null,
"assertions": [
{
"id": "d4e5f6a7-89ab-cdef-0123-4567890abcde",
"type": "LLM_JUDGE",
"name": "De-escalation",
"config": {
"prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?",
"output_type": "score",
"threshold": 0.7
},
"is_required": true,
"weight": 1.5,
"order": 0
}
],
"created_at": "2026-04-14T00:00:00.000Z"
}
Agent Testing
Create Test Scenario
Create a new test scenario with assertions for a pathway or persona.
POST
/
v1
/
agent-testing
/
scenarios
Create Test Scenario
curl --request POST \
--url https://api.bland.ai/v1/agent-testing/scenarios \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"pathway_id": "<string>",
"persona_id": "<string>",
"name": "<string>",
"description": "<string>",
"category": "<string>",
"scenario_type": "<string>",
"tester_persona_prompt": "<string>",
"tester_persona_name": "<string>",
"max_turns": 123,
"request_data": {},
"start_node_id": "<string>",
"bland_tone_enabled": true,
"is_required_for_promotion": true,
"input_messages": [
{}
],
"advanced_instructions": "<string>",
"metadata": {},
"assertions": [
{
"type": "<string>",
"config": {},
"name": "<string>",
"is_required": true,
"weight": 123,
"order": 123
}
]
}
'import requests
url = "https://api.bland.ai/v1/agent-testing/scenarios"
payload = {
"pathway_id": "<string>",
"persona_id": "<string>",
"name": "<string>",
"description": "<string>",
"category": "<string>",
"scenario_type": "<string>",
"tester_persona_prompt": "<string>",
"tester_persona_name": "<string>",
"max_turns": 123,
"request_data": {},
"start_node_id": "<string>",
"bland_tone_enabled": True,
"is_required_for_promotion": True,
"input_messages": [{}],
"advanced_instructions": "<string>",
"metadata": {},
"assertions": [
{
"type": "<string>",
"config": {},
"name": "<string>",
"is_required": True,
"weight": 123,
"order": 123
}
]
}
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({
pathway_id: '<string>',
persona_id: '<string>',
name: '<string>',
description: '<string>',
category: '<string>',
scenario_type: '<string>',
tester_persona_prompt: '<string>',
tester_persona_name: '<string>',
max_turns: 123,
request_data: {},
start_node_id: '<string>',
bland_tone_enabled: true,
is_required_for_promotion: true,
input_messages: [{}],
advanced_instructions: '<string>',
metadata: {},
assertions: [
{
type: '<string>',
config: {},
name: '<string>',
is_required: true,
weight: 123,
order: 123
}
]
})
};
fetch('https://api.bland.ai/v1/agent-testing/scenarios', 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/v1/agent-testing/scenarios",
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([
'pathway_id' => '<string>',
'persona_id' => '<string>',
'name' => '<string>',
'description' => '<string>',
'category' => '<string>',
'scenario_type' => '<string>',
'tester_persona_prompt' => '<string>',
'tester_persona_name' => '<string>',
'max_turns' => 123,
'request_data' => [
],
'start_node_id' => '<string>',
'bland_tone_enabled' => true,
'is_required_for_promotion' => true,
'input_messages' => [
[
]
],
'advanced_instructions' => '<string>',
'metadata' => [
],
'assertions' => [
[
'type' => '<string>',
'config' => [
],
'name' => '<string>',
'is_required' => true,
'weight' => 123,
'order' => 123
]
]
]),
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/v1/agent-testing/scenarios"
payload := strings.NewReader("{\n \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\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/v1/agent-testing/scenarios")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/agent-testing/scenarios")
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 \"pathway_id\": \"<string>\",\n \"persona_id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"category\": \"<string>\",\n \"scenario_type\": \"<string>\",\n \"tester_persona_prompt\": \"<string>\",\n \"tester_persona_name\": \"<string>\",\n \"max_turns\": 123,\n \"request_data\": {},\n \"start_node_id\": \"<string>\",\n \"bland_tone_enabled\": true,\n \"is_required_for_promotion\": true,\n \"input_messages\": [\n {}\n ],\n \"advanced_instructions\": \"<string>\",\n \"metadata\": {},\n \"assertions\": [\n {\n \"type\": \"<string>\",\n \"config\": {},\n \"name\": \"<string>\",\n \"is_required\": true,\n \"weight\": 123,\n \"order\": 123\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
"pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd",
"persona_id": null,
"name": "Angry Caller Test",
"description": "Tests the agent's ability to de-escalate an angry caller",
"category": "ANGRY_CALLER",
"scenario_type": "AGENT",
"tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.",
"tester_persona_name": "Frustrated Customer",
"max_turns": 15,
"request_data": null,
"start_node_id": null,
"bland_tone_enabled": true,
"is_required_for_promotion": false,
"enabled": true,
"input_messages": null,
"advanced_instructions": null,
"metadata": null,
"assertions": [
{
"id": "d4e5f6a7-89ab-cdef-0123-4567890abcde",
"type": "LLM_JUDGE",
"name": "De-escalation",
"config": {
"prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?",
"output_type": "score",
"threshold": 0.7
},
"is_required": true,
"weight": 1.5,
"order": 0
}
],
"created_at": "2026-04-14T00:00:00.000Z"
}
Headers
string
required
Your API key for authentication.
Body Parameters
string
The pathway to test. Either
pathway_id or persona_id is required.string
The persona to test. Either
pathway_id or persona_id is required.string
required
Name of the scenario. Must be unique within the pathway/persona.
string
Description of what the scenario tests.
string
default:"CUSTOM"
One of:
CUSTOM, VOICEMAIL, VOICEMAIL_SCREENER, ANGRY_CALLER, BELLIGERENT_CALLER, CONFUSED_CALLER, CALL_SCREENER, HAPPY_PATH, EDGE_CASE.string
default:"AGENT"
One of:
AGENT, REPLAY, HISTORICAL.string
Prompt instructing the simulated caller how to behave.
string
Display name for the tester persona.
integer
default:"20"
Max conversation turns before the test ends. Maximum value is 50.
object
Custom request data to pass to the pathway (e.g., variables).
string
ID of the pathway node where the simulated conversation should begin. Use this to test a specific branch of a pathway without rewiring the flow. When omitted (or
null), the test runs from the pathway’s default start node. If the ID does not match a node in the current pathway version, the run fails with an Invalid start_node_id error.boolean
default:"false"
Enable Bland Tone naturalness scoring.
boolean
default:"false"
If true, this scenario must pass before the pathway can be promoted to production.
array
Pre-seeded messages for
REPLAY scenarios.string
Additional instructions for test execution.
object
Arbitrary metadata to attach to the scenario.
array
Array of assertion definitions.
Show assertion object
Show assertion object
string
required
The assertion type. One of:
LLM_JUDGE, BLAND_TONE, VARIABLE_EXTRACTED, NODE_REACHED, NODES_VISITED, WEBHOOK_TRIGGERED, REGEX_MATCH, STRING_CHECK, CUSTOM_LLM, TRAVERSAL_MATCH.object
required
Type-specific configuration for the assertion.
string
Display name for the assertion.
boolean
default:"true"
Whether this assertion must pass for the scenario to pass.
number
default:"1.0"
Weight of this assertion in the overall score.
integer
Order in which the assertion is evaluated.
Response
string
Unique identifier for the created scenario.
string
Organization ID that owns this scenario.
string
The pathway ID being tested (null if testing a persona).
string
The persona ID being tested (null if testing a pathway).
string
Name of the scenario.
string
Description of the scenario.
string
Scenario category.
string
Type of scenario.
string
Prompt for the simulated caller.
string
Display name for the tester persona.
integer
Maximum conversation turns.
object
Custom request data.
string
Starting node ID.
boolean
Whether Bland Tone scoring is enabled.
boolean
Whether this scenario is required for promotion.
boolean
Whether the scenario is enabled.
array
Pre-seeded messages for replay scenarios.
string
Additional instructions for test execution.
object
Arbitrary metadata.
array
Array of assertion objects.
string
ISO 8601 timestamp of when the scenario was created.
{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"org_id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
"pathway_id": "c3d4e5f6-789a-bcde-f012-34567890abcd",
"persona_id": null,
"name": "Angry Caller Test",
"description": "Tests the agent's ability to de-escalate an angry caller",
"category": "ANGRY_CALLER",
"scenario_type": "AGENT",
"tester_persona_prompt": "You are a frustrated customer who has been waiting on hold for 30 minutes. You are upset about a billing error on your account.",
"tester_persona_name": "Frustrated Customer",
"max_turns": 15,
"request_data": null,
"start_node_id": null,
"bland_tone_enabled": true,
"is_required_for_promotion": false,
"enabled": true,
"input_messages": null,
"advanced_instructions": null,
"metadata": null,
"assertions": [
{
"id": "d4e5f6a7-89ab-cdef-0123-4567890abcde",
"type": "LLM_JUDGE",
"name": "De-escalation",
"config": {
"prompt": "Did the agent successfully de-escalate the situation and address the customer's concerns?",
"output_type": "score",
"threshold": 0.7
},
"is_required": true,
"weight": 1.5,
"order": 0
}
],
"created_at": "2026-04-14T00:00:00.000Z"
}
Docs for agents: llms.txt
Was this page helpful?
⌘I