Skip to main content
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
    }
  ]
}
'
{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bland.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
pathway_id
string
The pathway to test. Either pathway_id or persona_id is required.
​
persona_id
string
The persona to test. Either pathway_id or persona_id is required.
​
name
string
required
Name of the scenario. Must be unique within the pathway/persona.
​
description
string
Description of what the scenario tests.
​
category
string
default:"CUSTOM"
One of: CUSTOM, VOICEMAIL, VOICEMAIL_SCREENER, ANGRY_CALLER, BELLIGERENT_CALLER, CONFUSED_CALLER, CALL_SCREENER, HAPPY_PATH, EDGE_CASE.
​
scenario_type
string
default:"AGENT"
One of: AGENT, REPLAY, HISTORICAL.
​
tester_persona_prompt
string
Prompt instructing the simulated caller how to behave.
​
tester_persona_name
string
Display name for the tester persona.
​
max_turns
integer
default:"20"
Max conversation turns before the test ends. Maximum value is 50.
​
request_data
object
Custom request data to pass to the pathway (e.g., variables).
​
start_node_id
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.
​
bland_tone_enabled
boolean
default:"false"
Enable Bland Tone naturalness scoring.
​
is_required_for_promotion
boolean
default:"false"
If true, this scenario must pass before the pathway can be promoted to production.
​
input_messages
array
Pre-seeded messages for REPLAY scenarios.
​
advanced_instructions
string
Additional instructions for test execution.
​
metadata
object
Arbitrary metadata to attach to the scenario.
​
assertions
array
Array of assertion definitions.

​
Response

​
id
string
Unique identifier for the created scenario.
​
org_id
string
Organization ID that owns this scenario.
​
pathway_id
string
The pathway ID being tested (null if testing a persona).
​
persona_id
string
The persona ID being tested (null if testing a pathway).
​
name
string
Name of the scenario.
​
description
string
Description of the scenario.
​
category
string
Scenario category.
​
scenario_type
string
Type of scenario.
​
tester_persona_prompt
string
Prompt for the simulated caller.
​
tester_persona_name
string
Display name for the tester persona.
​
max_turns
integer
Maximum conversation turns.
​
request_data
object
Custom request data.
​
start_node_id
string
Starting node ID.
​
bland_tone_enabled
boolean
Whether Bland Tone scoring is enabled.
​
is_required_for_promotion
boolean
Whether this scenario is required for promotion.
​
enabled
boolean
Whether the scenario is enabled.
​
input_messages
array
Pre-seeded messages for replay scenarios.
​
advanced_instructions
string
Additional instructions for test execution.
​
metadata
object
Arbitrary metadata.
​
assertions
array
Array of assertion objects.
​
created_at
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