Generate Scenario Instructions with AI

Authorizations

X-CEKURA-API-KEY

string

header

required

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

Body

Mixin for parsing restql query from request.

NOTE: We are using request.GET instead of request.query_params because this might be called before DRF request is created(i.e from dispatch). This means request.query_params might not be available when this mixin is used.

personality

integer

required

Personality ID Example: 123

name

string

Name of the scenario

Maximum string length: 80

agent

integer

Agent ID Example: 2142

project

integer | null

assistant_id

string

write-only

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

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"]

metrics

any

write-only

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

first_message

string

First message to be sent to the Main Agent

Maximum string length: 1000

inbound_phone_number

integer | null

instructions

string

Scenario Instructions

conditional_actions

any

write-only

Structured conditional-actions object for scenario_type="conditional_actions". Use either conditional_actions (structured) or instructions (plain text) — not both.

Example:

{
  "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

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

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

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)

Response

200 - application/json

Mixin for parsing restql query from request.

personality

integer

required

Personality ID Example: 123

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"]

runs

string

read-only

List of IDs for the last run of this scenario Example: [123, 456]

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"

Show child attributes

first_message

string

First message to be sent to the Main Agent

Maximum string length: 1000

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"}

Show child attributes

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 Example:

{
    "id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "information": {
        "user_name": "<string>",
        "user_email": "<string>",
        "order_id": "<string>",
    },
}

Show child attributes

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

max_duration

integer | null

API Reference

Documentation Index

Authorizations

Body

Response