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

Scopes the permission check to a specific agent (either this or project is required). When provided, also overrides each evaluator's agent to this ID.

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 describing the caller's 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 must send via this field, pass the same object as a JSON-formatted string. The earlier id-based format (id, condition, action, type, fixed_message) is still accepted on writes. Responses return this shape unless conditional_actions_format=legacy is passed:

{
  "role": "A friendly customer calling about an appointment",
  "first_message": "Hi, I'd like to check on my upcoming appointment <silence time=\"1.5s\" />",
  "conditions": [
    {"when": "The agent asks for your name", "say": "My name is Sarah Johnson"},
    {"when": "The agent asks for your date of birth", "say": "January first, nineteen ninety"},
    {
      "when": "The agent confirms your identity and provides appointment details",
      "say": "Thank you, that's all I needed",
      "then": ["<endcall />"]
    }
  ]
}

Structure:

role: Personality/role description
first_message: What the caller says first; empty means wait for the agent. Use {"say": "...", "then": [...]} to add follow-ups.
conditions[].when: A third-person description of the agent's observable action, matched semantically against the conversation
conditions[].say: The caller's reply, spoken verbatim. Wrap the whole step in <ai_generated>...</ai_generated> to let the caller improvise from it instead
conditions[].then: Optional follow-up steps, each fired on the caller's next turn after one agent reply, in order
Steps support SSML <silence time="1.5s" /> (interruptible), <hold time="2s" /> (not interruptible), [laughter] and <endcall /> in verbatim steps

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
kk - Kazakh
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
uz - Uzbek
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,

kk,

ko,

ms,

ml,

mr,

multi,

no,

pl,

pa,

pt,

ro,

ru,

sk,

es,

sv,

th,

tr,

tl,

ta,

te,

uk,

uz,

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

instruction - Instruction
conditional_actions - Conditional Actions

Available options:

instruction,

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

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

REMOVED FROM API. Historically stored a flat copy of the agent's dynamic-variable values for the scenario. The column is retained read-only for legacy rows; reads still return its historical value, but writes via the API are rejected with a 400. At call time the Run-level helper consults this column ONLY when the attached test_profile is legacy-flat (or absent) — sectioned test profiles are the canonical source and ignore this column. Put dynamic-variable values in test_profile.information.main_agent_variables for new scenarios.

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

read-only

ID of the user who created this scenario

last_updated_by

integer | null

read-only

ID of the user who last updated this scenario

folder_path

string | null

Path of an existing folder to assign this evaluator to, e.g. "Sales" or "Sales.Inbound". Create it first with the create-folder endpoint.