> ## 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.

# Generate Evaluator

> Generate test scenarios in the background



## OpenAPI

````yaml post /test_framework/v1/scenarios/generate-bg/
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/generate-bg/:
    post:
      tags:
        - test_framework
      description: >-
        Generate scenarios for a given agent in the background. Returns a
        `progress_id` immediately; poll GET
        /scenarios/generate-progress/?progress_id={id} until `total_scenarios ==
        completed_scenarios`.


        **What happens automatically on generation:**

        - A scenario-specific test profile is created and its `information` is
        populated using the sectioned shape: `main_agent_variables`
        (dynamic-variable values that reach the agent under test at call time —
        e.g. `user_id`, `account_id`) and `testing_agent_variables`
        (persona/context used by the simulated caller — e.g. `customer_name`,
        `date_of_birth`). Section values are kept consistent with any generated
        mock-tool data.

        - 10 project-level evaluation metrics are attached to every generated
        scenario automatically (e.g. Latency, Pitch, Interruption Score).
        Scenarios created manually via `scenarios_create` start with no metrics
        attached.


        **Response fields:** `progress_id` (UUID string) for polling;
        `session_id` is always null.
      operationId: scenarios-generate-bg_2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaGenerateScenarios'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SchemaGenerateScenarios'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SchemaGenerateScenarios'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  progress_id:
                    type: string
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  field_name:
                    type: array
                    items:
                      type: string
          description: ''
      security:
        - api_key: []
components:
  schemas:
    SchemaGenerateScenarios:
      type: object
      properties:
        agent_id:
          type: integer
          description: ID of the agent to generate evaluator for
        assistant_id:
          type: string
          description: >-
            Alternative to agent_id - the assistant ID to generate evaluators
            for
        personalities:
          type: array
          items:
            type: integer
          description: List of personality IDs to use for generated evaluators
        num_scenarios:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of evaluators to generate (1-100)
        test_profile:
          type: integer
          description: ID of the test profile to assign to generated evaluators
        scenario_type:
          enum:
            - workflow
            - red_teaming_voice
            - red_teaming_text
            - knowledge_base
          type: string
          x-spec-enum-id: 4ef5c62a43e5fdd9
          default: workflow
          description: >-
            Type of scenarios to generate: workflow (standard scenarios),
            red_teaming_voice (red teaming with voice-suitable prompts only),
            red_teaming_text (red teaming with all prompts), or knowledge_base
            (knowledge base scenarios)


            * `workflow` - workflow

            * `red_teaming_voice` - red_teaming_voice

            * `red_teaming_text` - red_teaming_text

            * `knowledge_base` - knowledge_base
        attack_type:
          enum:
            - ''
            - system_prompt_leak
            - data_leak
            - harmful_content
            - biased_output
            - unauthorized_actions
            - off_task
            - null
          type:
            - string
            - 'null'
          x-spec-enum-id: 70525e347169b18e
          description: >-
            Attack category for red teaming scenarios. Required when
            scenario_type is red_teaming_voice or red_teaming_text. Categories:
            system_prompt_leak (attempts to extract the system prompt),
            data_leak (attempts to extract sensitive data), harmful_content
            (attempts to generate harmful output), biased_output (attempts to
            generate biased responses), unauthorized_actions (attempts to
            trigger unauthorized tool calls or actions), off_task (attempts to
            derail the conversation away from the agent's purpose)


            * `` - 

            * `system_prompt_leak` - system_prompt_leak

            * `data_leak` - data_leak

            * `harmful_content` - harmful_content

            * `biased_output` - biased_output

            * `unauthorized_actions` - unauthorized_actions

            * `off_task` - off_task
        expected_outcome:
          type:
            - string
            - 'null'
          description: >-
            Custom expected outcome for the scenario. If not provided, a default
            is generated based on the attack type.
        knowledge_base:
          type: array
          items:
            type: integer
          description: >-
            List of Knowledge Base file IDs for the agent to reference during
            scenario generation
        extra_instructions:
          type: string
          description: Additional instructions to guide evaluator generation
        inbound_phone_number:
          type:
            - integer
            - 'null'
          description: Phone number ID to use for inbound evaluator
        first_message:
          type: string
          default: Hello
          description: Initial message to start the conversation
          maxLength: 1000
        generate_expected_outcomes:
          type: boolean
          default: false
          description: If true, expected outcomes will be generated for each evaluator
        tags:
          type: array
          items:
            type: string
          description: List of tags to apply to all generated scenarios
        tool_ids:
          type: array
          items:
            type: string
          description: List of tool IDs to use for generated evaluators
          example:
            - TOOL_DTMF
            - TOOL_END_CALL
            - TOOL_END_CALL_ONLY_ON_TRANSFER
        folder_path:
          type:
            - string
            - 'null'
          description: >-
            Folder path to assign generated scenarios to (e.g., 'folder_name' or
            'parent.child')
      required:
        - num_scenarios
  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.

````