Skip to main content
POST
/
test_framework
/
v1
/
scenarios
Create an evaluator (scenario)
curl --request POST \
  --url https://api.cekura.ai/test_framework/v1/scenarios/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "personality": 123,
  "agent": 123,
  "project": 123,
  "assistant_id": "<string>",
  "name": "<string>",
  "scenario_type": "instruction",
  "instructions": "<string>",
  "expected_outcome_prompt": "<string>",
  "metrics": [
    123
  ],
  "tags": [
    "<string>"
  ],
  "tool_ids": [
    "TOOL_DTMF",
    "TOOL_END_CALL",
    "TOOL_END_CALL_ONLY_ON_TRANSFER"
  ],
  "test_profile": 123,
  "phone_number": 123,
  "inbound_phone_number": 123,
  "folder_path": "<string>"
}
'
{
  "id": 123,
  "name": "<string>",
  "agent": 123,
  "project": 123,
  "personality": 123,
  "personality_name": "<string>",
  "agent_name": "<string>",
  "tags": [
    "<string>"
  ],
  "tool_ids": "<unknown>",
  "runs": [
    123
  ],
  "metrics": [
    123
  ],
  "metric_names": [
    "<string>"
  ],
  "phone_number": "<string>",
  "outbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "first_message": "<string>",
  "inbound_phone_number": 123,
  "inbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "instructions": "<string>",
  "simulation_description": "<string>",
  "information_fields": {},
  "expected_outcome_prompt": "<string>",
  "scenario_language": "af",
  "scenario_type": "<string>",
  "suite_type": "undefined",
  "is_predefined": true,
  "test_profile": 123,
  "test_profile_data": {
    "name": "<string>",
    "id": 123,
    "project": 123,
    "agent": 123,
    "information": {}
  },
  "dynamic_variable_values": "<unknown>",
  "folder_path": "<string>",
  "max_duration": 123
}

Authorizations

​
X-CEKURA-API-KEY
string
header
required

API Key Authentication. It should be included in the header of each request.

Body

​
personality
integer
required

The personality of the evaluator

​
agent
integer | null

ID of the agent. Either agent or project must be provided.

​
project
integer | null

ID of the project. Either agent or project must be provided.

​
assistant_id
string

Alternative to agent ID - the assistant ID to use for this scenario Example: "asst_1234567890"

​
name
string

Name of the scenario

Maximum string length: 80
​
scenario_type
enum<string>
default:instruction

Type of scenario to create:

  • instruction: Standard instruction-based scenario where the instructions field contains plain text
  • conditional_actions: Conditional action-based scenario where the instructions field contains a JSON structure

Default: instruction

  • instruction - Instruction
  • conditional_actions - Conditional Actions
Available options:
instruction,
conditional_actions
​
instructions
string

Scenario Instructions - the format depends on the scenario_type:

For scenario_type="instruction": Provide plain text instructions that describe the scenario behavior. Example: "You are a customer calling to inquire about your order status. Be polite and provide order number 12345 when asked."

For scenario_type="conditional_actions": Provide a JSON-formatted string (stringified) with the following structure:

{
  "role": "A friendly customer calling about an appointment",
  "conditions": [
    {
      "id": 0,
      "condition": "FIRST_MESSAGE",
      "action": "Hi there, I need to check on my appointment <break time=\"1.5s\" /> [laughter]",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 1,
      "condition": "contains \"appointment\" OR contains \"schedule\" OR contains \"help\"",
      "action": "Yes, I have an appointment scheduled for tomorrow [laughter] [laughter]",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 2,
      "condition": "contains \"confirm\" OR contains \"thank\" OR contains \"anything else\"",
      "action": "No that's all, thank you so much <break time=\"1.0s\" /> [laughter]",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 3,
      "condition": 2,
      "action": "<endcall />",
      "type": "action_followup",
      "fixed_message": true
    }
  ]
}

Important: The JSON must be stringified (use JSON.dumps in Python or JSON.stringify in JavaScript) before sending.

Structure Details:

  • role (string): Personality/role description for the scenario actor

  • conditions (array): Ordered list of conditional actions that define the conversation flow

    Each condition object has:

    • id (integer): Unique sequential identifier (0, 1, 2, 3...)

    • condition (string | integer): The trigger that activates this action

      • "FIRST_MESSAGE" - Triggers at conversation start (use for id: 0)
      • "contains \"keyword\"" - Triggers when agent's response contains keyword(s)
      • Use OR for multiple keywords: "contains \"word1\" OR contains \"word2\"
      • Use AND for all keywords: "contains \"word1\" AND contains \"word2\"
      • Integer (e.g., 2) - References another condition's id for sequential followup actions

    • action (string): What the scenario actor says or does

      • SSML pause tags: <break time="1.5s" /> or <break time="1.0s" />
      • Emotion markers: [laughter], [sigh], etc. (can repeat like [laughter] [laughter])
      • Special actions: <endcall /> to end the call

    • type (string): Either "standard" (normal response) or "action_followup" (triggers after another condition)

    • fixed_message (boolean): Set to true for fixed responses, false for dynamic

Usage Tips:

  • Always start with id: 0 and condition: "FIRST_MESSAGE"
  • Use the last condition to trigger <endcall /> for clean call termination
  • Combine SSML tags and emotion markers naturally: "Great <break time=\"1.5s\" /> [laughter] [laughter]"
  • The contains operators are case-insensitive
​
conditional_actions
object

Structured conditional-actions payload — preferred over posting a stringified JSON via instructions for scenario_type="conditional_actions". When supplied, the backend converts this object to a JSON string and stores it in the scenario's instructions field automatically.

Use either conditional_actions (structured) OR instructions (stringified JSON) — not both.

​
expected_outcome_prompt
string

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

​
metrics
integer[]

List of metric IDs to associate with this evaluator Example: [123, 456, 789]

​
tags
string[]

List of tags to associate with the evaluator Example: ["tag1", "tag2", "tag3"]

​
tool_ids
string[]

List of tool IDs to use for evaluator

Example:
[
  "TOOL_DTMF",
  "TOOL_END_CALL",
  "TOOL_END_CALL_ONLY_ON_TRANSFER"
]
​
test_profile
integer

The test profile ID to use for the evaluator

​
phone_number
integer

The phone number ID to use for the evaluator (works for both inbound and outbound)

​
inbound_phone_number
integer

(Deprecated) The inbound phone number ID to use for the evaluator. Use phone_number instead, which works for both inbound and outbound.

​
folder_path
string | null

Dot-separated folder path to assign the evaluator to (e.g. "Sales.Inbound")

Response

​
id
integer
​
name
string

Name of the evaluator

​
agent
integer

Agent ID Example: 2142

​
project
integer | null
​
personality
integer

ID of the personality

​
personality_name
string

Name of the personality

​
agent_name
string

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

​
tags
string[]

List of tags of the evaluators Example: ["tag1", "tag2", "tag3"]

​
tool_ids
any

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

​
runs
integer[]

List of run IDs Example: [123, 456, 789]

​
metrics
integer[]

List of metric IDs Example: [123, 456, 789]

​
metric_names
string[]

List of metric names Example: ["Metric 1", "Metric 2", "Metric 3"]

​
phone_number
string

Phone number eg: +17776666333

​
outbound_phone_number_data
object

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

​
first_message
string

First message of the evaluator

​
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 - format depends on scenario_type:

  • For instruction type: Plain text instructions
  • For conditional_actions type: JSON string with role and conditions array. Each condition has id, condition trigger (FIRST_MESSAGE, contains operators, or id reference), action (text with optional <break time="1.5s" /> and [laughter] tags), type (standard/action_followup), and fixed_message flag
​
simulation_description
string

Simulation Description

​
information_fields
object

Information fields of the evaluator Example:

{
    "user_name": "John Doe",
    "user_email": "john.doe@example.com",
}
​
expected_outcome_prompt
string

Expected outcome prompt of the evaluator 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
  • 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,
ta,
te,
uk,
vi
​
scenario_type
string

Type of scenario:

  • instruction: Standard instruction-based scenario (plain text instructions)
  • conditional_actions: Conditional action-based scenario (JSON with role, conditions, SSML tags, emotion markers)
  • real_world_smart: Real world smart scenario
  • real_world_fixed: Real world fixed scenario
​
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 Example:

{
    "id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "information": {
        "user_name": "<string>",
        "user_email": "<string>",
        "order_id": "<string>",
    },
}
​
dynamic_variable_values
any | null

Generated values for the agent's dynamic variables for this scenario. Keys are variable names; values are the generated values.

​
folder_path
string · null · null

Path of the folder this scenario belongs to

​
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)