> ## 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.

# Create Test Scenario

> Create a new test scenario with assertions for a pathway or persona.

### 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.

**assertion object**

**type** `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`.

**config** `object` *required*

Type-specific configuration for the assertion.

**name** `string`

Display name for the assertion.

**is\_required** `boolean` (default: true)

Whether this assertion must pass for the scenario to pass.

**weight** `number` (default: 1.0)

Weight of this assertion in the overall score.

**order** `integer`

Order in which the assertion is evaluated.

### 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.

**assertion object**

**id** `string`

Unique identifier for the assertion.

**type** `string`

The assertion type.

**name** `string`

Display name for the assertion.

**config** `object`

Type-specific configuration.

**is\_required** `boolean`

Whether this assertion must pass.

**weight** `number`

Weight of this assertion in the overall score.

**order** `integer`

Evaluation order.

**created\_at** `string`

ISO 8601 timestamp of when the scenario was created.

```json Response theme={null}
{
  "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](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.