Create Scenario

Creates a new scenario -- a test case that pairs one or more personas with target agents and a scorecard for automated evaluation.

Endpoint

POST /api/v1/scenarios

curl -X POST "https://api.chanl.ai/api/v1/scenarios" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Dispute Resolution",
    "prompt": "You are calling about an unexpected charge on your account. You want it explained and resolved.",
    "personaIds": ["persona_123", "persona_456"],
    "agentIds": ["agent_789"],
    "scorecardId": "scorecard_345",
    "tags": ["billing", "customer-service"],
    "promptVariables": [
      {
        "name": "charge_amount",
        "type": "string",
        "defaultValue": "$29.99"
      }
    ]
  }'

const response = await fetch('https://api.chanl.ai/api/v1/scenarios', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Billing Dispute Resolution',
    prompt: 'You are calling about an unexpected charge on your account. You want it explained and resolved.',
    personaIds: ['persona_123', 'persona_456'],
    agentIds: ['agent_789'],
    scorecardId: 'scorecard_345',
    tags: ['billing', 'customer-service'],
    promptVariables: [
      {
        name: 'charge_amount',
        type: 'string',
        defaultValue: '$29.99',
      },
    ],
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.chanl.ai/api/v1/scenarios',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'name': 'Billing Dispute Resolution',
        'prompt': 'You are calling about an unexpected charge on your account. You want it explained and resolved.',
        'personaIds': ['persona_123', 'persona_456'],
        'agentIds': ['agent_789'],
        'scorecardId': 'scorecard_345',
        'tags': ['billing', 'customer-service'],
        'promptVariables': [
            {
                'name': 'charge_amount',
                'type': 'string',
                'defaultValue': '$29.99',
            },
        ],
    },
)
data = response.json()

Parameters

namestringrequired

Display name for the scenario. Must be unique within the workspace.

promptstringrequired

Instructions that define the test situation. Supports Liquid variables (e.g., {{charge_amount}}).

personaIdsstring[]required

Array of persona IDs to simulate as callers. Each persona generates a separate simulation when the scenario is executed.

agentIdsstring[]required

Array of agent IDs to test against. Each agent is paired with every persona during execution.

scorecardIdstringrequired

ID of the scorecard used to evaluate simulation results.

tagsstring[]

Tags for filtering and organization.

promptVariablesobject[]

Variables available in the prompt template. Each object has name (string), type (string), and defaultValue (string).

Response

{
  "success": true,
  "data": {
    "scenario": {
      "id": "scenario_abc123",
      "name": "Billing Dispute Resolution",
      "prompt": "You are calling about an unexpected charge on your account. You want it explained and resolved.",
      "promptVariables": [
        {
          "name": "charge_amount",
          "type": "string",
          "defaultValue": "$29.99"
        }
      ],
      "personas": [
        { "id": "persona_123", "name": "Frustrated Customer" },
        { "id": "persona_456", "name": "Polite Customer" }
      ],
      "targetAgents": [
        { "id": "agent_789", "name": "Support Agent v2" }
      ],
      "scorecard": {
        "id": "scorecard_345",
        "name": "Customer Service Quality"
      },
      "tags": ["billing", "customer-service"],
      "created_at": "2025-03-17T10:30:00Z",
      "updated_at": "2025-03-17T10:30:00Z",
      "created_by": {
        "id": "user_123",
        "name": "John Doe"
      }
    }
  }
}

Errors

Status	Code	Description
400	`validation_error`	Invalid or missing required fields
401	`unauthorized`	Missing or invalid access token
404	`not_found`	One or more referenced persona, agent, or scorecard IDs do not exist
409	`conflict`	A scenario with this name already exists in the workspace

Create Scenario

Create Scenario

Endpoint

Parameters

Response

Errors

On this page