{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cekura-ai/json-schema/cekura-ai-scenario-list-schema.json",
  "title": "ScenarioList",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cekura-ai-evaluators-api-openapi.yml#/components/schemas/ScenarioList",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true,
      "description": "\nUnique identifier for the AI agent\nExample: `123`\n"
    },
    "name": {
      "type": "string",
      "description": "Name of the scenario",
      "maxLength": 80
    },
    "personality": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Foreign key reference to the personality used in this scenario"
    },
    "personality_name": {
      "type": "string",
      "readOnly": true,
      "description": "\nName of the personality used in this scenario\nExample: `\"Normal Male\"`\n"
    },
    "agent_name": {
      "type": "string",
      "readOnly": true,
      "description": "\nName of the agent associated with this scenario\nExample: `\"Customer Support Agent\"`\n"
    },
    "phone_number": {
      "type": "string",
      "readOnly": true
    },
    "expected_outcome_prompt": {
      "type": "string",
      "readOnly": true,
      "description": "\nExpected outcome prompt for the scenario\nExample: `\"The user should be able to complete the order\"`\n"
    },
    "instructions": {
      "type": "string",
      "description": "\nScenario Instructions - format depends on scenario_type:\n\n**For scenario_type=\"instruction\":**\nPlain text describing the caller's behavior.\nExample: `\"You are a customer calling to inquire about your order status. Be polite and provide order number 12345 when asked.\"`\n\n**For scenario_type=\"conditional_actions\":**\nUse the structured `conditional_actions` field instead. If you must send via this field, pass the same object as a JSON-formatted string. The earlier id-based format (`id`, `condition`, `action`, `type`, `fixed_message`) is still accepted on writes. Responses return this shape unless `conditional_actions_format=legacy` is passed:\n```json\n{\n  \"role\": \"A friendly customer calling about an appointment\",\n  \"first_message\": \"Hi, I'd like to check on my upcoming appointment <silence time=\\\"1.5s\\\" />\",\n  \"conditions\": [\n    {\"when\": \"The agent asks for your name\", \"say\": \"My name is Sarah Johnson\"},\n    {\"when\": \"The agent asks for your date of birth\", \"say\": \"January first, nineteen ninety\"},\n    {\n      \"when\": \"The agent confirms your identity and provides appointment details\",\n      \"say\": \"Thank you, that's all I needed\",\n      \"then\": [\"<endcall />\"]\n    }\n  ]\n}\n```\n\n**Structure:**\n- `role`: Personality/role description\n- `first_message`: What the caller says first; empty means wait for the agent. Use `{\"say\": \"...\", \"then\": [...]}` to add follow-ups.\n- `conditions[].when`: A third-person description of the agent's observable action, matched semantically against the conversation\n- `conditions[].say`: The caller's reply, spoken verbatim. Wrap the whole step in `<ai_generated>...</ai_generated>` to let the caller improvise from it instead\n- `conditions[].then`: Optional follow-up steps, each fired on the caller's next turn after one agent reply, in order\n- Steps support SSML `<silence time=\"1.5s\" />` (interruptible), `<hold time=\"2s\" />` (not interruptible), `[laughter]` and `<endcall />` in verbatim steps\n"
    },
    "scenario_language": {
      "enum": [
        "af",
        "ar",
        "bn",
        "bg",
        "zh",
        "cs",
        "da",
        "nl",
        "en",
        "et",
        "fi",
        "fr",
        "de",
        "el",
        "gu",
        "hi",
        "he",
        "hu",
        "id",
        "it",
        "ja",
        "kn",
        "kk",
        "ko",
        "ms",
        "ml",
        "mr",
        "multi",
        "no",
        "pl",
        "pa",
        "pt",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "th",
        "tr",
        "tl",
        "ta",
        "te",
        "uk",
        "uz",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "x-spec-enum-id": "f996e9ef7edb7fea",
      "description": "Language code for the scenario (ISO language code)\n\n* `af` - Afrikaans\n* `ar` - Arabic\n* `bn` - Bengali\n* `bg` - Bulgarian\n* `zh` - Chinese Simplified\n* `cs` - Czech\n* `da` - Danish\n* `nl` - Dutch\n* `en` - English\n* `et` - Estonian\n* `fi` - Finnish\n* `fr` - French\n* `de` - German\n* `el` - Greek\n* `gu` - Gujarati\n* `hi` - Hindi\n* `he` - Hebrew\n* `hu` - Hungarian\n* `id` - Indonesian\n* `it` - Italian\n* `ja` - Japanese\n* `kn` - Kannada\n* `kk` - Kazakh\n* `ko` - Korean\n* `ms` - Malay\n* `ml` - Malayalam\n* `mr` - Marathi\n* `multi` - Multilingual\n* `no` - Norwegian\n* `pl` - Polish\n* `pa` - Punjabi\n* `pt` - Portuguese\n* `ro` - Romanian\n* `ru` - Russian\n* `sk` - Slovak\n* `es` - Spanish\n* `sv` - Swedish\n* `th` - Thai\n* `tr` - Turkish\n* `tl` - Tagalog\n* `ta` - Tamil\n* `te` - Telugu\n* `uk` - Ukrainian\n* `uz` - Uzbek\n* `vi` - Vietnamese"
    },
    "scenario_type": {
      "enum": [
        "instruction",
        "conditional_actions"
      ],
      "type": "string",
      "x-spec-enum-id": "97f8e4b948b4e205",
      "default": "instruction",
      "description": "\nType of scenario:\n- `instruction`: Standard instruction-based scenario where instructions field contains plain text\n- `conditional_actions`: Conditional action-based scenario where instructions field contains JSON\n\n\n* `instruction` - Instruction\n* `conditional_actions` - Conditional Actions"
    },
    "tags": {
      "description": "\nList of tags associated with this scenario for categorization\nExample: `[\"tag1\", \"tag2\", \"tag3\"]`\n"
    },
    "agent": {
      "type": "integer",
      "description": "Foreign key reference to the AI agent that owns this scenario"
    },
    "inbound_phone_number": {
      "type": [
        "integer",
        "null"
      ],
      "description": "(Deprecated) Foreign key reference to the phone number. Use phone_number field instead. This field is maintained for backward compatibility and will be automatically synced with phone_number."
    },
    "inbound_phone_number_data": {
      "type": "string",
      "readOnly": true,
      "description": "Details of the phone number used for inbound calls"
    },
    "metrics": {
      "type": "string",
      "readOnly": true,
      "description": "List of metrics associated with this scenario for evaluation"
    },
    "metric_names": {
      "type": "string",
      "readOnly": true,
      "description": "\nList of metric names associated with this scenario\nExample: `[\"Metric 1\", \"Metric 2\", \"Metric 3\"]`\n"
    },
    "first_message": {
      "type": "string",
      "default": "Hello",
      "description": "The initial message that the AI agent will send when the scenario starts"
    },
    "tool_ids": {
      "description": "\nList of tool IDs that are available for use in this scenario\nExample: `[\"TOOL_DTML\", \"TOOL_END_CALL\"]`\n"
    },
    "test_profile": {
      "type": [
        "integer",
        "null"
      ],
      "description": "\nTest profile ID\nExample: `123`\n"
    },
    "test_profile_data": {
      "allOf": [
        {
          "$ref": "#/$defs/AIAgentTestProfile"
        }
      ],
      "readOnly": true,
      "description": "\nDetails of the test profile associated with this scenario\nExample:\n```json\n{\n    \"id\": \"<integer>\",\n    \"agent\": \"<integer>\",\n    \"name\": \"<string>\",\n    \"information\": {\n        \"user_name\": \"John Doe\",\n        \"user_email\": \"john.doe@example.com\",\n    }\n}\n```\n"
    },
    "dynamic_variable_values": {
      "oneOf": [
        {},
        {
          "type": "null"
        }
      ],
      "description": "REMOVED FROM API. Historically stored a flat copy of the agent's dynamic-variable values for the scenario. The column is retained read-only for legacy rows; reads still return its historical value, but writes via the API are rejected with a 400. At call time the Run-level helper consults this column ONLY when the attached test_profile is legacy-flat (or absent) — sectioned test profiles are the canonical source and ignore this column. Put dynamic-variable values in `test_profile.information.main_agent_variables` for new scenarios."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Timestamp when the scenario was created"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "readOnly": true,
      "description": "Timestamp when the scenario was last updated"
    },
    "created_by": {
      "type": [
        "integer",
        "null"
      ],
      "readOnly": true,
      "description": "ID of the user who created this scenario"
    },
    "last_updated_by": {
      "type": [
        "integer",
        "null"
      ],
      "readOnly": true,
      "description": "ID of the user who last updated this scenario"
    },
    "folder_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Path of an existing folder to assign this evaluator to, e.g. \"Sales\" or \"Sales.Inbound\". Create it first with the create-folder endpoint."
    }
  },
  "required": [
    "agent",
    "instructions",
    "name"
  ],
  "$defs": {
    "AIAgentTestProfile": {
      "type": "object",
      "description": "",
      "properties": {
        "id": {
          "type": "integer",
          "readOnly": true
        },
        "project": {
          "type": [
            "integer",
            "null"
          ]
        },
        "agent": {
          "type": [
            "integer",
            "null"
          ]
        },
        "agent_name": {
          "type": "string",
          "readOnly": true,
          "description": "\nName of the agent associated with this test profile\nExample: `\"Customer Support Agent\"`\n"
        },
        "name": {
          "type": "string",
          "maxLength": 255
        },
        "information": {
          "description": "\nVariables for the test profile, split by which agent receives them.\n```json\n{\n    \"main_agent_variables\": {\"user_id\": \"U-123\"},\n    \"testing_agent_variables\": {\"user_name\": \"John Doe\", \"user_email\": \"john.doe@example.com\"}\n}\n```\n`main_agent_variables` are sent to the agent under test as dynamic variables. `testing_agent_variables` shape the simulated caller's persona. A legacy flat dict (no section keys) is accepted for backward compatibility and is sent to both agents.\n\nKeys in `main_agent_variables` starting with `X-` are additionally sent as custom SIP headers (SIP runs) or connection headers (WebSocket runs) to the agent under test. For SIP runs this is the only way to pass custom headers; `X-Run-Id`, `X-Scenario-Id`, and `X-Result-Id` are reserved and always set by Cekura.\n"
        },
        "created_by": {
          "type": [
            "integer",
            "null"
          ],
          "readOnly": true,
          "description": "ID of the user who created this test profile"
        },
        "last_updated_by": {
          "type": [
            "integer",
            "null"
          ],
          "readOnly": true,
          "description": "ID of the user who last updated this test profile"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "Timestamp when the test profile was created"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "Timestamp when the test profile was last updated"
        }
      },
      "required": [
        "name"
      ]
    }
  }
}