> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk Update Evaluators
> Bulk-update many evaluators in a single call: attach/detach metrics or tools, switch personality, append instructions, move into a folder, or change phone number / max duration.
## OpenAPI
````yaml post /test_framework/v1/scenarios/adv_update/
openapi: 3.1.0
info:
title: Cekura API
version: v1
description: >-
Complete API documentation for the Cekura platform. This API provides
endpoints for testing, observing, and evaluating AI voice agents — including
managing agents, running evaluators, defining metrics, and analyzing call
quality.
servers:
- url: https://api.cekura.ai
security: []
paths:
/test_framework/v1/scenarios/adv_update/:
post:
tags:
- Evaluators
summary: Bulk update evaluators
description: >-
Update many evaluators in a single call. Useful for attaching/detaching
metrics, switching personality, appending instructions, or moving a
batch between folders.
**Non-idempotent fields:** `append_instruction` concatenates — calling
twice with the same string adds it twice.
`metric_ids_to_add`/`metric_ids_to_remove` and
`tool_ids_to_add`/`tool_ids_to_remove` are set-mutating and shouldn't be
replayed blindly.
**Affects every ID in `scenarios`.** For modifying a single evaluator,
prefer `scenarios_partial_update`. Confirm the `scenarios` list with the
user before calling — the change is applied across the whole list in one
transaction.
**Required:** `scenarios` (list of evaluator IDs). One of `agent` or
`project` is also required to scope the permission check. All other
fields are optional and are applied only when present.
operationId: scenarios-bulk-update_2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScenariosBulkUpdateRequest'
examples:
AttachTwoMetricsToABatchOfScenarios:
value:
agent: 12
scenarios:
- 101
- 102
- 103
metric_ids_to_add:
- 501
- 502
summary: Attach two metrics to a batch of scenarios
MoveScenariosIntoAFolderAndSwitchPersonality:
value:
agent: 12
scenarios:
- 101
- 102
folder_path: Sales.Inbound
personality: 7
summary: Move scenarios into a folder and switch personality
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ScenariosBulkUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ScenariosBulkUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScenarioList'
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
field_name:
type: array
items:
type: string
description: ''
security:
- api_key: []
components:
schemas:
ScenariosBulkUpdateRequest:
type: object
properties:
scenarios:
type: array
items:
type: integer
description: List of evaluator (scenario) IDs to update.
agent:
type: integer
description: >-
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:
type: integer
description: >-
Scope the permission check to a specific project. Either this or
`agent` is required.
metric_ids_to_add:
type: array
items:
type: integer
description: Metric IDs to attach to each evaluator.
metric_ids_to_remove:
type: array
items:
type: integer
description: Metric IDs to detach from each evaluator.
tool_ids_to_add:
type: array
items:
type: integer
description: Tool IDs to attach to each evaluator.
tool_ids_to_remove:
type: array
items:
type: integer
description: Tool IDs to detach from each evaluator.
personality:
type: integer
description: Replace each evaluator's personality with this ID.
test_profile:
type: integer
description: Replace each evaluator's test profile with this ID.
append_instruction:
type: string
description: >-
Text appended to every evaluator's instructions. Concatenates on
each call — not idempotent.
first_message:
type: string
description: Replace each evaluator's first message.
phone_number:
type: integer
description: Replace each evaluator's outbound phone number ID.
inbound_phone_number:
type: integer
description: Replace each evaluator's inbound phone number ID.
folder_path:
type: string
description: >-
Move every evaluator into this folder. Dot-separated (e.g.
"Sales.Inbound").
max_duration:
type: integer
description: Replace each evaluator's max duration in seconds.
required:
- scenarios
ScenarioList:
type: object
description: ''
properties:
id:
type: integer
readOnly: true
description: |
Unique identifier for the AI agent
Example: `123`
name:
type: string
description: Name of the scenario
maxLength: 80
personality:
type:
- integer
- 'null'
description: Foreign key reference to the personality used in this scenario
personality_name:
type: string
readOnly: true
description: |
Name of the personality used in this scenario
Example: `"Normal Male"`
agent_name:
type: string
readOnly: true
description: |
Name of the agent associated with this scenario
Example: `"Customer Support Agent"`
phone_number:
type: string
readOnly: true
expected_outcome_prompt:
type: string
readOnly: true
description: |
Expected outcome prompt for the scenario
Example: `"The user should be able to complete the order"`
instructions:
type: string
description: >
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 a JSON-formatted string with role and
conditions:
```json
{
"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 ",
"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 ",
"type": "standard",
"fixed_message": true
},
{
"id": 4,
"condition": 3,
"action": "",
"type": "action_followup",
"fixed_message": true
}
]
}
```
**Structure:**
- `role`: Personality/role description
- `conditions`: Array with id (0,1,2...), condition (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 against the conversation context | integer
reference to another condition's id), action (text with SSML
`` (interruptible) or ``
(not interruptible) and markers `[laughter]` or ``), type
(standard | action_followup), fixed_message (boolean)
scenario_language:
enum:
- 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
- null
type:
- string
- 'null'
x-spec-enum-id: b822ad429c7b7fec
description: |-
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
* `tl` - Tagalog
* `ta` - Tamil
* `te` - Telugu
* `uk` - Ukrainian
* `vi` - Vietnamese
scenario_type:
enum:
- instruction
- real_world_smart
- real_world_fixed
- conditional_actions
type: string
x-spec-enum-id: db62e37bb530b602
default: instruction
description: >-
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
tags:
description: |
List of tags associated with this scenario for categorization
Example: `["tag1", "tag2", "tag3"]`
agent:
type: integer
description: Foreign key reference to the AI agent that owns this scenario
inbound_phone_number:
type:
- integer
- 'null'
description: >-
(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:
type: string
readOnly: true
description: Details of the phone number used for inbound calls
metrics:
type: string
readOnly: true
description: List of metrics associated with this scenario for evaluation
metric_names:
type: string
readOnly: true
description: |
List of metric names associated with this scenario
Example: `["Metric 1", "Metric 2", "Metric 3"]`
first_message:
type: string
default: Hello
description: >-
The initial message that the AI agent will send when the scenario
starts
tool_ids:
description: |
List of tool IDs that are available for use in this scenario
Example: `["TOOL_DTML", "TOOL_END_CALL"]`
test_profile:
type:
- integer
- 'null'
description: |
Test profile ID
Example: `123`
test_profile_data:
allOf:
- $ref: '#/components/schemas/AIAgentTestProfile'
readOnly: true
description: |
Details of the test profile associated with this scenario
Example:
```json
{
"id": "",
"agent": "",
"name": "",
"information": {
"user_name": "John Doe",
"user_email": "john.doe@example.com",
}
}
```
dynamic_variable_values:
oneOf:
- {}
- type: 'null'
description: >-
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:
type: string
format: date-time
readOnly: true
description: Timestamp when the scenario was created
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the scenario was last updated
created_by:
type: integer
readOnly: true
description: ID of the user who created this scenario
last_updated_by:
type: integer
readOnly: true
description: ID of the user who last updated this scenario
folder_path:
type:
- string
- 'null'
- 'null'
description: >-
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.
required:
- agent
- instructions
- name
AIAgentTestProfile:
type: object
properties:
id:
type: integer
readOnly: true
project:
type:
- integer
- 'null'
agent:
type:
- integer
- 'null'
agent_name:
type: string
readOnly: true
description: |
Name of the agent associated with this test profile
Example: `"Customer Support Agent"`
name:
type: string
maxLength: 255
information:
description: >
Variables for the test profile, split by which agent receives them.
```json
{
"main_agent_variables": {"user_id": "U-123"},
"testing_agent_variables": {"user_name": "John Doe", "user_email": "john.doe@example.com"}
}
```
`main_agent_variables` are sent to the agent under test as dynamic
variables. `testing_agent_variables` shape the simulated caller's
persona. A legacy flat dict (no section keys) is accepted for
backward compatibility and is sent to both agents.
created_by:
type: integer
readOnly: true
description: ID of the user who created this test profile
last_updated_by:
type: integer
readOnly: true
description: ID of the user who last updated this test profile
created_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the test profile was created
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the test profile was last updated
required:
- name
securitySchemes:
api_key:
type: apiKey
name: X-CEKURA-API-KEY
in: header
description: >-
API Key Authentication. It should be included in the header of each
request.
````