Create Evaluator

Authorizations

X-CEKURA-API-KEY

string

header

required

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

Body

name

string

required

Name of the evaluator

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

write-only

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

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": Use the structured conditional_actions field instead. If you send via instructions, pass a JSON-formatted string with the following structure:

{
  "role": "A friendly customer calling about an appointment",
  "conditions": [
    {
      "id": 0,
      "condition": "FIRST_MESSAGE",
      "action": "Hi, I'd like to check on my upcoming appointment <silence time=\"1.5s\" />",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 1,
      "condition": "The agent asks for your name",
      "action": "My name is Sarah Johnson",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 2,
      "condition": "The agent asks for your date of birth",
      "action": "January first, nineteen ninety",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 3,
      "condition": "The agent confirms your identity and provides appointment details",
      "action": "Thank you, that's all I needed <silence time=\"1.0s\" />",
      "type": "standard",
      "fixed_message": true
    },
    {
      "id": 4,
      "condition": 3,
      "action": "<endcall />",
      "type": "action_followup",
      "fixed_message": true
    }
  ]
}

Note: When sent via instructions, the value must be a JSON-formatted string (e.g. JSON.stringify(...) / json.dumps(...)). For new integrations, use the structured conditional_actions field below.

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)
  - Natural-language description of the main agent's observable action, written from a third-person observer perspective (e.g. "The agent asks for your date of birth", "The agent confirms the cancellation"). Matched semantically against the conversation context.
  - Integer (e.g. 3) — References another condition's id for sequential action_followup chaining
- action (string): What the scenario actor says or does
  - SSML pause tags: <silence time="1.5s" /> (interruptible) or <hold time="2s" /> (not interruptible). <silence> lets the main agent jump in mid-pause; <hold> enforces dead air.
  - 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" (fires on the testing agent's next turn after the referenced condition — one main-agent reply elapses in between, regardless of its content; never fires in the same turn as its parent)
- fixed_message (boolean): Set to true for fixed responses, false for dynamic

Usage Tips:

Always start with id: 0 and condition: "FIRST_MESSAGE"
Write conditions as third-person descriptions of what the main agent does (e.g. "The agent confirms the cancellation")
Use the last condition to trigger <endcall /> for clean call termination
Combine SSML tags and emotion markers naturally: "Great <silence time=\"1.5s\" /> [laughter] [laughter]"

conditional_actions

object

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

Show child attributes

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]

Response

integer

read-only

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

read-only

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

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"

Show child attributes

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

Show child attributes

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, a natural-language third-person description of the main agent's observable action — e.g. "The agent asks for your date of birth", matched semantically — or an integer reference to another condition's id), action (text with optional <silence time="1.5s" /> (interruptible) or <hold time="2s" /> (not interruptible) 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",
}

Show child attributes

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

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

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

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)

API Reference

Documentation Index

Authorizations

Body

Response