Update Scenario

Replaces the configuration of an existing scenario. All mutable fields can be updated in a single request.

Endpoint

PUT /api/v1/scenarios/:id

curl -X PUT "https://api.chanl.ai/api/v1/scenarios/scenario_abc123" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Billing Inquiry",
    "prompt": "You are calling about a billing issue that needs immediate attention.",
    "personaIds": ["persona_123", "persona_456", "persona_789"],
    "agentIds": ["agent_789"],
    "scorecardId": "scorecard_345",
    "tags": ["billing", "escalation"]
  }'

const response = await fetch('https://api.chanl.ai/api/v1/scenarios/scenario_abc123', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Enhanced Billing Inquiry',
    prompt: 'You are calling about a billing issue that needs immediate attention.',
    personaIds: ['persona_123', 'persona_456', 'persona_789'],
    agentIds: ['agent_789'],
    scorecardId: 'scorecard_345',
    tags: ['billing', 'escalation'],
  }),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.chanl.ai/api/v1/scenarios/scenario_abc123',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'name': 'Enhanced Billing Inquiry',
        'prompt': 'You are calling about a billing issue that needs immediate attention.',
        'personaIds': ['persona_123', 'persona_456', 'persona_789'],
        'agentIds': ['agent_789'],
        'scorecardId': 'scorecard_345',
        'tags': ['billing', 'escalation'],
    },
)
data = response.json()

Path Parameters

idstringrequired

The scenario ID (e.g., scenario_abc123).

Parameters

namestring

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

promptstring

Instructions that define the test situation. Supports Liquid variables.

personaIdsstring[]

Array of persona IDs to simulate as callers.

agentIdsstring[]

Array of agent IDs to test against.

scorecardIdstring

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": "Enhanced Billing Inquiry",
      "prompt": "You are calling about a billing issue that needs immediate attention.",
      "promptVariables": [],
      "personas": [
        { "id": "persona_123", "name": "Frustrated Customer" },
        { "id": "persona_456", "name": "Polite Customer" },
        { "id": "persona_789", "name": "Confused Customer" }
      ],
      "targetAgents": [
        { "id": "agent_789", "name": "Support Agent v2" }
      ],
      "scorecard": {
        "id": "scorecard_345",
        "name": "Customer Service Quality"
      },
      "tags": ["billing", "escalation"],
      "status": "active",
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-03-17T10:45:00Z",
      "created_by": {
        "id": "user_567",
        "name": "Jane Smith"
      }
    }
  }
}

Errors

Status	Code	Description
400	`validation_error`	Invalid request body
401	`unauthorized`	Missing or invalid access token
404	`not_found`	Scenario or referenced resource not found
409	`conflict`	A scenario with this name already exists in the workspace

Update Scenario

Update Scenario

Endpoint

Path Parameters

Parameters

Response

Errors

On this page