Skip to main content
POST
/
test_framework
/
v1
/
scenarios
/
generate-instructions
/
cURL
curl --request POST \
  --url https://api.cekura.ai/test_framework/v1/scenarios/generate-instructions/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "personality": 123,
  "name": "<string>",
  "agent": 123,
  "project": 123,
  "assistant_id": "<string>",
  "tags": "<unknown>",
  "tool_ids": "<unknown>",
  "metrics": "<unknown>",
  "first_message": "<string>",
  "inbound_phone_number": 123,
  "instructions": "<string>",
  "conditional_actions": "<unknown>",
  "simulation_description": "<string>",
  "information_fields": "<unknown>",
  "expected_outcome_prompt": "<string>",
  "scenario_type": "instruction",
  "is_predefined": true,
  "test_profile": 123,
  "folder_path": "<string>",
  "max_duration": 123
}
'
{
  "personality": 123,
  "id": 123,
  "name": "<string>",
  "agent": 123,
  "project": 123,
  "personality_name": "<string>",
  "agent_name": "<string>",
  "tags": "<unknown>",
  "tool_ids": "<unknown>",
  "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": "<unknown>",
  "expected_outcome_prompt": "<string>",
  "scenario_type": "instruction",
  "is_predefined": true,
  "test_profile": 123,
  "test_profile_data": {
    "name": "<string>",
    "id": 123,
    "project": 123,
    "agent": 123,
    "agent_name": "<string>",
    "information": "<unknown>",
    "created_by": 123,
    "last_updated_by": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dynamic_variable_values": "<unknown>",
  "generated_mock_tool_entries": "<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

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

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

{
    "id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "information": {
        "main_agent_variables": {
            "user_id": "<string>",
            "account_id": "<string>"
        },
        "testing_agent_variables": {
            "user_name": "<string>",
            "user_email": "<string>",
            "order_id": "<string>"
        }
    }
}
​
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
read-only

Expected mock tool calls generated for this evaluator during scenario auto-generation when the agent has mock tools attached. Each entry has shape {tool_id, tool_name, new_entry: {input, output}}.

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