> ## Documentation Index > Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt > Use this file to discover all available pages before exploring further. # Fetch Scenarios JSON Schema > Fetch the JSON Schema for test-suite spec files ## OpenAPI ````yaml get /test_framework/v1/scenarios/json_schema/ openapi: 3.1.0 info: title: Cekura API version: v1 description: >- Complete API documentation for the Cekura platform. This API provides endpoints for testing, observing, and evaluating AI voice agents — including managing agents, running evaluators, defining metrics, and analyzing call quality. servers: - url: https://api.cekura.ai security: [] paths: /test_framework/v1/scenarios/json_schema/: get: tags: - Evaluators summary: Fetch the JSON Schema for test-suite spec files description: Fetch the JSON Schema for test-suite spec files operationId: scenarios-json-schema_2 parameters: - in: query name: version schema: type: string description: Spec version to fetch. Defaults to the current version. responses: '200': content: application/json: schema: $ref: '#/components/schemas/Scenario' description: '' security: - oauth2: [] - supabase_session: [] - api_key: [] components: schemas: Scenario: type: object description: '' properties: id: type: integer readOnly: true name: type: string description: Name of the scenario maxLength: 80 agent: type: integer description: | Agent ID Example: `2142` project: type: - integer - 'null' assistant_id: type: string writeOnly: true description: | Alternative to agent ID - the assistant ID to use for this scenario Example: `"asst_1234567890"` personality: type: integer description: | Personality ID Example: `123` personality_name: type: string readOnly: true description: | Name of the personality used in this scenario Example: `"Normal Male"` agent_name: type: string readOnly: true description: | Name of the agent associated with this scenario Example: `"Customer Support Agent"` tags: description: | Tags associated with the scenario Example: `["tag1", "tag2"]` tool_ids: description: | List of tool IDs to associate with this scenario Example: `["TOOL_DTMF", "TOOL_END_CALL"]` metrics: writeOnly: true description: | List of metric IDs to associate with this scenario Example: `[123, 456]` metric_names: type: string readOnly: true description: | List of metric names associated with this scenario Example: `["Metric 1", "Metric 2"]` phone_number: type: string readOnly: true description: | Phone number used for outbound calls in this scenario Example: `"+1234567890"` outbound_phone_number_data: allOf: - $ref: '#/components/schemas/PhoneNumberInbound' readOnly: true description: | Phone number used for outbound calls in this scenario Example: `"+1234567890"` first_message: type: string description: First message to be sent to the Main Agent inbound_phone_number: type: - integer - 'null' inbound_phone_number_data: allOf: - $ref: '#/components/schemas/PhoneNumberInbound' readOnly: true description: > (Deprecated) Phone number used for inbound calls in this scenario. Use outbound_phone_number_data instead. After CEK-6517, both phone_number and inbound_phone_number fields are synced, so outbound_phone_number_data contains the unified phone number for both inbound and outbound calls. Example: `{"id": 123, "number": "+1234567890", "phone_number_id": "abc123"}` instructions: type: string description: Scenario Instructions conditional_actions: writeOnly: true description: >- Structured conditional-actions object for `scenario_type="conditional_actions"`. Use either `conditional_actions` (structured) or `instructions` (plain text) — not both. Example: ```json { "role": "You are a patient calling to schedule an appointment", "conditions": [ {"id": 0, "condition": "FIRST_MESSAGE", "action": "Hi, I need to schedule an appointment", "type": "standard", "fixed_message": true}, {"id": 1, "condition": "when the agent asks for your name", "action": "Provide your full name: John Smith", "type": "standard", "fixed_message": false} ] } ``` simulation_description: type: string description: Simulation Description information_fields: description: > Information fields associated with the scenario Example: `{"user_name": "John Doe", "user_email": "john.doe@example.com", "order_id": "1234567890"}` expected_outcome_prompt: type: string description: | Expected Outcome Prompt Example: `"The user should be able to complete the order"` 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 - ko - ms - ml - mr - multi - 'no' - pl - pa - pt - ro - ru - sk - es - sv - th - tr - tl - ta - te - uk - vi type: string x-spec-enum-id: b822ad429c7b7fec description: |- Language of the scenario * `af` - Afrikaans * `ar` - Arabic * `bn` - Bengali * `bg` - Bulgarian * `zh` - Chinese Simplified * `cs` - Czech * `da` - Danish * `nl` - Dutch * `en` - English * `et` - Estonian * `fi` - Finnish * `fr` - French * `de` - German * `el` - Greek * `gu` - Gujarati * `hi` - Hindi * `he` - Hebrew * `hu` - Hungarian * `id` - Indonesian * `it` - Italian * `ja` - Japanese * `kn` - Kannada * `ko` - Korean * `ms` - Malay * `ml` - Malayalam * `mr` - Marathi * `multi` - Multilingual * `no` - Norwegian * `pl` - Polish * `pa` - Punjabi * `pt` - Portuguese * `ro` - Romanian * `ru` - Russian * `sk` - Slovak * `es` - Spanish * `sv` - Swedish * `th` - Thai * `tr` - Turkish * `tl` - Tagalog * `ta` - Tamil * `te` - Telugu * `uk` - Ukrainian * `vi` - Vietnamese scenario_type: enum: - instruction - real_world_smart - real_world_fixed - conditional_actions type: string x-spec-enum-id: db62e37bb530b602 default: instruction description: >- Type of scenario (instruction, real_world_smart, or real_world_fixed) * `instruction` - Instruction * `real_world_smart` - Real World Smart * `real_world_fixed` - Real World Fixed * `conditional_actions` - Conditional Actions suite_type: enum: - undefined - infrastructure type: string x-spec-enum-id: 643f6a8cdc799a77 description: |- Type of predefined suite (e.g., infrastructure) * `undefined` - Undefined * `infrastructure` - Infrastructure is_predefined: type: boolean description: Whether this is a predefined scenario (template) test_profile: type: - integer - 'null' test_profile_data: allOf: - $ref: '#/components/schemas/AIAgentTestProfile' readOnly: true description: > Details of the test profile associated with this scenario. `information` uses the sectioned shape: `main_agent_variables` are sent to the agent under test as dynamic variables at call time; `testing_agent_variables` are persona/context used by Cekura's simulated caller. Legacy flat dicts (no section keys) still work — at call time they are delivered to both sides for backward compatibility. Example: ```json { "id": "", "agent_id": "", "name": "", "information": { "main_agent_variables": { "user_id": "", "account_id": "" }, "testing_agent_variables": { "user_name": "", "user_email": "", "order_id": "" } } } ``` dynamic_variable_values: readOnly: true description: >- REMOVED FROM API. Reads return the historical value for legacy rows (`null` for new rows). Writes are no longer accepted — supplying a non-null value yields a 400 error. Put dynamic-variable values in `test_profile_data.information.main_agent_variables` instead: create the test profile via POST /test-profiles/ and attach it via the `test_profile` field on the scenario. generated_mock_tool_entries: oneOf: - {} - type: 'null' description: >- Expected mock tool calls for this evaluator. Each entry has shape {tool_id, tool_name, new_entry: {input, output}}. Auto-generated during scenario generation when the agent has mock tools attached; can also be set or edited manually. folder_path: type: - string - 'null' - 'null' description: >- Dot-separated path of the folder to assign this evaluator to (e.g. "Sales.Inbound"). Folders must be created before use — they are not auto-created. Use `scenarios_create_folder_create` to create each level before assigning evaluators. Example: to use "Sales.Inbound", first create "Sales", then create "Inbound" inside it. max_duration: type: - integer - 'null' description: > Max call duration in seconds for this scenario. If not provided or set to null, the scenario will use the project's max_call_duration setting. Valid range: 10-3600 seconds (10 seconds to 60 minutes) Example: `600` (10 minutes) required: - personality PhoneNumberInbound: type: object properties: id: type: integer readOnly: true number: type: string maxLength: 15 phone_number_id: type: string maxLength: 255 required: - number - phone_number_id 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: | Name of the agent associated with this test profile Example: `"Customer Support Agent"` name: type: string maxLength: 255 information: description: > Variables for the test profile, split by which agent receives them. ```json { "main_agent_variables": {"user_id": "U-123"}, "testing_agent_variables": {"user_name": "John Doe", "user_email": "john.doe@example.com"} } ``` `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. Keys 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. created_by: type: integer readOnly: true description: ID of the user who created this test profile last_updated_by: type: integer 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 securitySchemes: oauth2: type: http scheme: bearer bearerFormat: JWT description: OAuth access token issued by Cekura for connected apps. supabase_session: type: http scheme: bearer bearerFormat: JWT description: Cekura dashboard session token. Not a customer API credential. api_key: type: apiKey in: header name: X-CEKURA-API-KEY description: >- API Key Authentication. It should be included in the header of each request. ````