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
}

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.

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. Pass as a list of integers [101, 102], a single integer 101, or the string "all" to improve all evaluators for the agent. Do not pass IDs as a JSON-stringified list — pass them as a native array.

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

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

​
session_id
integer
required

Session tracking ID