Bulk Update Evaluators

Authorizations

X-CEKURA-API-KEY

string

header

required

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

Body

scenarios

integer[]

required

List of evaluator (scenario) IDs to update.

agent

integer

Scope the permission check to a specific agent. Either this or project is required.

project

integer

Scope the permission check to a specific project. Either this or agent is required.

metric_ids_to_add

integer[]

Metric IDs to attach to each evaluator.

metric_ids_to_remove

integer[]

Metric IDs to detach from each evaluator.

tool_ids_to_add

integer[]

Tool IDs to attach to each evaluator.

tool_ids_to_remove

integer[]

Tool IDs to detach from each evaluator.

personality

integer

Replace each evaluator's personality with this ID.

test_profile

integer

Replace each evaluator's test profile with this ID.

append_instruction

string

Text appended to every evaluator's instructions. Concatenates on each call — not idempotent.

first_message

string

Replace each evaluator's first message.

phone_number

integer

Replace each evaluator's outbound phone number ID.

inbound_phone_number

integer

Replace each evaluator's inbound phone number ID.

folder_path

string

Move every evaluator into this folder. Dot-separated (e.g. "Sales.Inbound").

max_duration

integer

Replace each evaluator's max duration in seconds.

Response

name

string

required

Name of the scenario

Maximum string length: 80

instructions

string

required

Scenario Instructions - format depends on scenario_type:

For scenario_type="instruction": Plain text instructions describing 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": JSON-formatted string (stringified) with role and conditions:

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

Structure:

role: Personality/role description
conditions: Array with id (0,1,2...), condition (FIRST_MESSAGE | contains operators with OR/AND | condition id reference), action (text with SSML <break time="1.5s" /> and markers [laughter] or <endcall />), type (standard | action_followup), fixed_message (boolean)

agent

integer

required

Foreign key reference to the AI agent that owns this scenario

integer

read-only

Unique identifier for the AI agent Example: 123

personality

integer | null

Foreign key reference to the personality used in this scenario

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"

phone_number

string

read-only

expected_outcome_prompt

string

read-only

Expected outcome prompt for the scenario Example: "The user should be able to complete the order"

scenario_language

enum<string> | null

Language code for the scenario (ISO language code)

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,

null

scenario_type

enum<string>

default:instruction

Type of scenario:

instruction: Standard instruction-based scenario where instructions field contains plain text
conditional_actions: Conditional action-based scenario where instructions field contains JSON
real_world_smart: Real world smart scenario
real_world_fixed: Real world fixed scenario

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

tags

any

List of tags associated with this scenario for categorization Example: ["tag1", "tag2", "tag3"]

inbound_phone_number

integer | null

(Deprecated) Foreign key reference to the phone number. Use phone_number field instead. This field is maintained for backward compatibility and will be automatically synced with phone_number.

inbound_phone_number_data

string

read-only

Details of the phone number used for inbound calls

metrics

string

read-only

List of metrics associated with this scenario for evaluation

metric_names

string

read-only

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

first_message

string

default:Hello

The initial message that the AI agent will send when the scenario starts

Maximum string length: 1000

tool_ids

any

List of tool IDs that are available for use in this scenario Example: ["TOOL_DTML", "TOOL_END_CALL"]

test_profile

integer | null

Test profile ID Example: 123

test_profile_data

object

Details of the test profile associated with this scenario Example:

{
    "id": "<integer>",
    "agent": "<integer>",
    "name": "<string>",
    "information": {
        "user_name": "John Doe",
        "user_email": "john.doe@example.com",
    }
}

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.

created_at

string<date-time>

read-only

Timestamp when the scenario was created

updated_at

string<date-time>

read-only

Timestamp when the scenario was last updated

created_by

integer

read-only

ID of the user who created this scenario

last_updated_by

integer

read-only

ID of the user who last updated this scenario

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.

API Reference

Documentation Index

Authorizations

Body

Response