Skip to main content
POST
/
test_framework
/
v1
/
scenarios
/
scenario-agent
cURL
curl --request POST \
  --url https://api.cekura.ai/test_framework/v1/scenarios/scenario-agent/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "user_message": "",
  "agent_id": 123,
  "project_id": 123,
  "session_id": 123,
  "context": [
    {
      "role": "user",
      "content": "<string>"
    }
  ],
  "num_scenarios": 1,
  "knowledge_base": [
    123
  ],
  "scenarios": "<unknown>",
  "apply_changes": false,
  "updated_scenarios": [
    {}
  ],
  "agent_resolution_response": "",
  "scenarios_needing_agent": [
    123
  ],
  "pending_tool_calls": [
    {}
  ]
}
'
{
  "progress_id": "<string>",
  "session_id": 123
}

Authorizations

​
X-CEKURA-API-KEY
string
header
required

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

Body

Improve evaluators using AI by providing natural language feedback.

Provide evaluator IDs and your improvement request, and the AI will suggest changes.

​
user_message
string
default:""

Your improvement request (e.g., 'Make instructions more detailed')

​
agent_id
integer | null

Agent ID - optional, automatically inferred from evaluators if not provided

​
project_id
integer | null

Project ID - optional, automatically inferred from evaluators if not provided

​
session_id
integer | null

Session ID for tracking - automatically created if not provided

​
context
object[] | null

Conversation history for multi-turn improvements. Allows iterative refinement without sessions.

Example:

[
   {
      "role": "user",
      "content": "Add DTMF tool to all evaluators"
   },
   {
      "role": "assistant",
      "content": "Added DTMF tool to 3 evaluators"
   },
   {
      "role": "user",
      "content": "Make the instructions more detailed"
   },
   {
      "role": "assistant",
      "content": "Updated instructions to be more detailed for 3 evaluators"
   }
]
​
num_scenarios
integer
default:1

Number of scenarios to generate in clarify mode

Required range: x >= 1
​
knowledge_base
integer[]

Knowledge Base file IDs for additional context in clarify mode

​
scenarios
any | null

Evaluator IDs to improve. Provide as list [1, 2, 3] or string 'all'

​
apply_changes
boolean
default:false

Set to true to apply the AI-suggested changes to your evaluators

​
updated_scenarios
object[]

AI-suggested changes from previous response - use with apply_changes=true to apply them

​
agent_resolution_response
string
default:""

User's response when agent clarification was needed

​
scenarios_needing_agent
integer[]

Evaluator IDs that required agent selection

​
pending_tool_calls
object[] | null

Tool calls held from a previous agent-clarification response

Response

​
progress_id
string

Use this to poll for results at /scenario-agent-progress/?progress_id={id}

​
session_id
integer

Session tracking ID