Skip to main content
GET
Fetch the JSON Schema for test-suite spec files

Authorizations

Authorization
string
header
required

OAuth access token issued by Cekura for connected apps.

Query Parameters

version
string

Spec version to fetch. Defaults to the current version.

Response

200 - application/json
personality
integer
required

Personality ID Example: 123

id
integer
read-only
name
string

Name of the scenario

Maximum string length: 80
agent
integer

Agent ID Example: 2142

project
integer | null
personality_name
string
read-only

Name of the personality used in this scenario Example: "Normal Male"

agent_name
string
read-only

Name of the agent associated with this scenario Example: "Customer Support Agent"

tags
any

Tags associated with the scenario Example: ["tag1", "tag2"]

tool_ids
any

List of tool IDs to associate with this scenario Example: ["TOOL_DTMF", "TOOL_END_CALL"]

metric_names
string
read-only

List of metric names associated with this scenario Example: ["Metric 1", "Metric 2"]

phone_number
string
read-only

Phone number used for outbound calls in this scenario Example: "+1234567890"

outbound_phone_number_data
object

Phone number used for outbound calls in this scenario Example: "+1234567890"

first_message
string

First message to be sent to the Main Agent

inbound_phone_number
integer | null
inbound_phone_number_data
object

(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
string

Scenario Instructions

simulation_description
string

Simulation Description

information_fields
any

Information fields associated with the scenario Example: {"user_name": "John Doe", "user_email": "john.doe@example.com", "order_id": "1234567890"}

expected_outcome_prompt
string

Expected Outcome Prompt Example: "The user should be able to complete the order"

scenario_language
enum<string>

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
Available options:
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
scenario_type
enum<string>
default:instruction

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
Available options:
instruction,
real_world_smart,
real_world_fixed,
conditional_actions
suite_type
enum<string>

Type of predefined suite (e.g., infrastructure)

  • undefined - Undefined
  • infrastructure - Infrastructure
Available options:
undefined,
infrastructure
is_predefined
boolean

Whether this is a predefined scenario (template)

test_profile
integer | null
test_profile_data
object

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:

dynamic_variable_values
any
read-only

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
any | null

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
string · null · null

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
integer | null

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)