Cekura · Schema

ScenarioSerializerV2

CompanyVoice AIQATestingBenchmarking

Properties

Name Type Description
id integer
name string Name of the scenario
agent integer Agent ID Example: `2142`
project integernull
assistant_id string Alternative to agent ID - the assistant ID to use for this scenario Example: `"asst_1234567890"`
personality integer Personality ID Example: `123`
personality_name string Name of the personality used in this scenario Example: `"Normal Male"`
agent_name string Name of the agent associated with this scenario Example: `"Customer Support Agent"`
tags object Tags associated with the scenario Example: `["tag1", "tag2"]`
tool_ids object List of tool IDs to associate with this scenario Example: `["TOOL_DTMF", "TOOL_END_CALL"]`
metrics object List of metric IDs to associate with this scenario Example: `[123, 456]`
metric_names string List of metric names associated with this scenario Example: `["Metric 1", "Metric 2"]`
phone_number integernull Phone number ID - Used for both inbound and outbound calls Example: `123`
outbound_phone_number_data object Phone number used for outbound calls in this scenario Example: `"+1234567890"`
first_message string First message to be sent to the Main Agent
inbound_phone_number integernull (Deprecated) Use phone_number instead. This field is maintained for backward compatibility only. When phone_number is set, this field will be automatically synced. Example: `123`
inbound_phone_number_data object (Deprecated) Phone number used for inbound calls in this scenario. Use outbound_phone_number_data instead. After CEK-6517, both phone_number and inbound_phone_number fields are synced, so outbound_pho
instructions string Scenario Instructions
conditional_actions object Structured conditional-actions object. Requires `scenario_type="conditional_actions"` in the same request, unless the scenario already has that type. Use either `conditional_actions` (structured) or `
condition_audio object Pre-recorded clips available to this scenario's conditional actions, keyed by clip id. Read-only: upload, replace and delete clips, and correct a transcript, through `condition-audio/`. Reference a cl
simulation_description string
information_fields object Information fields associated with the scenario Example: `{"user_name": "John Doe", "user_email": "john.doe@example.com", "order_id": "1234567890"}`
expected_outcome_prompt string Expected Outcome Prompt Example: `"The user should be able to complete the order"`
scenario_language string Language of the scenario * `af` - Afrikaans * `ar` - Arabic * `bn` - Bengali * `bg` - Bulgarian * `zh` - Chinese Simplified * `cs` - Czech * `da` - Danish * `nl` - Dutch * `en` - English * `et` - Esto
scenario_type string Type of scenario. Defaults to `instruction`. Must be sent as `conditional_actions` when the request includes the `conditional_actions` field. * `instruction` - Instruction * `conditional_actions` - Co
suite_type string Type of predefined suite (e.g., infrastructure) * `undefined` - Undefined * `infrastructure` - Infrastructure
is_predefined boolean Whether this is a predefined scenario (template)
test_profile integernull
test_profile_data object Details of the test profile associated with this scenario. `information` uses the sectioned shape: `main_agent_variables` are sent to the agent under test as dynamic variables at call time; `testing_a
dynamic_variable_values object REMOVED FROM API. Reads return the historical value for legacy rows (`null` for new rows). Writes are no longer accepted — supplying a non-null value yields a 400 error. Put dynamic-variable values in
generated_mock_tool_entries object Expected mock tool calls for this evaluator. Each entry has shape {tool_id, tool_name, new_entry: {input, output, response?}}. Auto-generated during scenario generation when the agent has mock tools a
folder_path stringnull Path of an existing folder to assign this evaluator to, e.g. "Sales" or "Sales.Inbound". Create it first with the create-folder endpoint.
max_duration integernull Max call duration in seconds for this scenario. If not provided or set to null, the scenario will use the project's max_call_duration setting. Valid range: 10-3600 seconds (10 seconds to 60 minutes) E
View JSON Schema on GitHub

JSON Schema

cekura-ai-scenario-serializer-v2-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cekura-ai/json-schema/cekura-ai-scenario-serializer-v2-schema.json",
  "title": "ScenarioSerializerV2",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cekura-ai-evaluators-api-openapi.yml#/components/schemas/ScenarioSerializerV2",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true
    },
    "name": {
      "type": "string",
      "description": "Name of the scenario",
      "maxLength": 80
    },
    "agent": {
      "type": "integer",
      "description": "\nAgent ID\nExample: `2142`\n"
    },
    "project": {
      "type": [
        "integer",
        "null"
      ]
    },
    "assistant_id": {
      "type": "string",
      "writeOnly": true,
      "description": "\nAlternative to agent ID - the assistant ID to use for this scenario\nExample: `\"asst_1234567890\"`\n"
    },
    "personality": {
      "type": "integer",
      "description": "\nPersonality ID\nExample: `123`\n"
    },
    "personality_name": {
      "type": "string",
      "readOnly": true,
      "description": "\nName of the personality used in this scenario\nExample: `\"Normal Male\"`\n"
    },
    "agent_name": {
      "type": "string",
      "readOnly": true,
      "description": "\nName of the agent associated with this scenario\nExample: `\"Customer Support Agent\"`\n"
    },
    "tags": {
      "description": "\nTags associated with the scenario\nExample: `[\"tag1\", \"tag2\"]`\n"
    },
    "tool_ids": {
      "description": "\nList of tool IDs to associate with this scenario\nExample: `[\"TOOL_DTMF\", \"TOOL_END_CALL\"]`\n"
    },
    "metrics": {
      "writeOnly": true,
      "description": "\nList of metric IDs to associate with this scenario\nExample: `[123, 456]`\n"
    },
    "metric_names": {
      "type": "string",
      "readOnly": true,
      "description": "\nList of metric names associated with this scenario\nExample: `[\"Metric 1\", \"Metric 2\"]`\n"
    },
    "phone_number": {
      "type": [
        "integer",
        "null"
      ],
      "description": "\nPhone number ID - Used for both inbound and outbound calls\nExample: `123`\n"
    },
    "outbound_phone_number_data": {
      "allOf": [
        {
          "$ref": "#/$defs/PhoneNumberInbound"
        }
      ],
      "readOnly": true,
      "description": "\nPhone number used for outbound calls in this scenario\nExample: `\"+1234567890\"`\n"
    },
    "first_message": {
      "type": "string",
      "description": "First message to be sent to the Main Agent"
    },
    "inbound_phone_number": {
      "type": [
        "integer",
        "null"
      ],
      "description": "\n(Deprecated) Use phone_number instead. This field is maintained for backward compatibility only.\nWhen phone_number is set, this field will be automatically synced.\nExample: `123`\n"
    },
    "inbound_phone_number_data": {
      "allOf": [
        {
          "$ref": "#/$defs/PhoneNumberInbound"
        }
      ],
      "readOnly": true,
      "description": "\n(Deprecated) Phone number used for inbound calls in this scenario. Use outbound_phone_number_data instead.\nAfter CEK-6517, both phone_number and inbound_phone_number fields are synced, so outbound_phone_number_data contains the unified phone number for both inbound and outbound calls.\nExample: `{\"id\": 123, \"number\": \"+1234567890\", \"phone_number_id\": \"abc123\"}`\n"
    },
    "instructions": {
      "type": "string",
      "description": "Scenario Instructions"
    },
    "conditional_actions": {
      "writeOnly": true,
      "description": "Structured conditional-actions object. Requires `scenario_type=\"conditional_actions\"` in the same request, unless the scenario already has that type. Use either `conditional_actions` (structured) or `instructions` (plain text) — not both. `first_message` is what the caller says first (empty means wait for the agent). Each condition's `say` is spoken verbatim; wrap a whole step in `<ai_generated>...</ai_generated>` to let the caller improvise from it. `then` steps fire in order, one per caller turn, after the agent replies. Responses return this format unless `conditional_actions_format=legacy` is passed. The earlier id-based format (`id`, `condition`, `action`, `type`, `fixed_message`) is also accepted.\n\nExample:\n```json\n{\n  \"role\": \"You are a patient calling to schedule an appointment\",\n  \"first_message\": \"Hi, I need to schedule an appointment\",\n  \"conditions\": [\n    {\"when\": \"the agent asks for your name\", \"say\": \"John Smith\",\n     \"then\": [\"<ai_generated>Confirm whichever details the agent reads back</ai_generated>\"]}\n  ]\n}\n```"
    },
    "condition_audio": {
      "type": "object",
      "additionalProperties": {},
      "readOnly": true,
      "description": "Pre-recorded clips available to this scenario's conditional actions, keyed by clip id. Read-only: upload, replace and delete clips, and correct a transcript, through `condition-audio/`. Reference a clip from any number of verbatim steps by pasting its `tag`; `steps` lists where it is used (e.g. `conditions[1].then[0]`).\n\nExample:\n```json\n{\n  \"greeting\": {\"tag\": \"<audio id=\\\"greeting\\\"/>\", \"filename\": \"greeting.wav\",\n               \"status\": \"ready\", \"duration\": 2.4, \"transcript\": \"Hi, is this the clinic?\",\n               \"steps\": [\"first_message\", \"conditions[1]\"]}\n}\n```"
    },
    "simulation_description": {
      "type": "string",
      "readOnly": true
    },
    "information_fields": {
      "description": "\nInformation fields associated with the scenario\nExample: `{\"user_name\": \"John Doe\", \"user_email\": \"john.doe@example.com\", \"order_id\": \"1234567890\"}`\n"
    },
    "expected_outcome_prompt": {
      "type": "string",
      "description": "\nExpected Outcome Prompt\nExample: `\"The user should be able to complete the order\"`\n"
    },
    "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",
        "kk",
        "ko",
        "ms",
        "ml",
        "mr",
        "multi",
        "no",
        "pl",
        "pa",
        "pt",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "th",
        "tr",
        "tl",
        "ta",
        "te",
        "uk",
        "uz",
        "vi"
      ],
      "type": "string",
      "x-spec-enum-id": "f996e9ef7edb7fea",
      "description": "\nLanguage of the scenario\n\n\n* `af` - Afrikaans\n* `ar` - Arabic\n* `bn` - Bengali\n* `bg` - Bulgarian\n* `zh` - Chinese Simplified\n* `cs` - Czech\n* `da` - Danish\n* `nl` - Dutch\n* `en` - English\n* `et` - Estonian\n* `fi` - Finnish\n* `fr` - French\n* `de` - German\n* `el` - Greek\n* `gu` - Gujarati\n* `hi` - Hindi\n* `he` - Hebrew\n* `hu` - Hungarian\n* `id` - Indonesian\n* `it` - Italian\n* `ja` - Japanese\n* `kn` - Kannada\n* `kk` - Kazakh\n* `ko` - Korean\n* `ms` - Malay\n* `ml` - Malayalam\n* `mr` - Marathi\n* `multi` - Multilingual\n* `no` - Norwegian\n* `pl` - Polish\n* `pa` - Punjabi\n* `pt` - Portuguese\n* `ro` - Romanian\n* `ru` - Russian\n* `sk` - Slovak\n* `es` - Spanish\n* `sv` - Swedish\n* `th` - Thai\n* `tr` - Turkish\n* `tl` - Tagalog\n* `ta` - Tamil\n* `te` - Telugu\n* `uk` - Ukrainian\n* `uz` - Uzbek\n* `vi` - Vietnamese"
    },
    "scenario_type": {
      "enum": [
        "instruction",
        "conditional_actions"
      ],
      "type": "string",
      "x-spec-enum-id": "97f8e4b948b4e205",
      "default": "instruction",
      "description": "\nType of scenario. Defaults to `instruction`. Must be sent as `conditional_actions` when the\nrequest includes the `conditional_actions` field.\n\n\n* `instruction` - Instruction\n* `conditional_actions` - Conditional Actions"
    },
    "suite_type": {
      "enum": [
        "undefined",
        "infrastructure"
      ],
      "type": "string",
      "x-spec-enum-id": "643f6a8cdc799a77",
      "description": "Type of predefined suite (e.g., infrastructure)\n\n* `undefined` - Undefined\n* `infrastructure` - Infrastructure"
    },
    "is_predefined": {
      "type": "boolean",
      "description": "Whether this is a predefined scenario (template)"
    },
    "test_profile": {
      "type": [
        "integer",
        "null"
      ]
    },
    "test_profile_data": {
      "allOf": [
        {
          "$ref": "#/$defs/AIAgentTestProfile"
        }
      ],
      "readOnly": true,
      "description": "\nDetails of the test profile associated with this scenario. `information` uses the\nsectioned shape: `main_agent_variables` are sent to the agent under test as\ndynamic variables at call time; `testing_agent_variables` are persona/context\nused by Cekura's simulated caller. Legacy flat dicts (no section keys) still\nwork — at call time they are delivered to both sides for backward compatibility.\nExample:\n```json\n{\n    \"id\": \"<integer>\",\n    \"agent_id\": \"<integer>\",\n    \"name\": \"<string>\",\n    \"information\": {\n        \"main_agent_variables\": {\n            \"user_id\": \"<string>\",\n            \"account_id\": \"<string>\"\n        },\n        \"testing_agent_variables\": {\n            \"user_name\": \"<string>\",\n            \"user_email\": \"<string>\",\n            \"order_id\": \"<string>\"\n        }\n    }\n}\n```\n"
    },
    "dynamic_variable_values": {
      "readOnly": true,
      "description": "REMOVED FROM API. Reads return the historical value for legacy rows (`null` for new rows). Writes are no longer accepted — supplying a non-null value yields a 400 error. Put dynamic-variable values in `test_profile_data.information.main_agent_variables` instead: create the test profile via POST /test-profiles/ and attach it via the `test_profile` field on the scenario."
    },
    "generated_mock_tool_entries": {
      "oneOf": [
        {},
        {
          "type": "null"
        }
      ],
      "description": "Expected mock tool calls for this evaluator. Each entry has shape {tool_id, tool_name, new_entry: {input, output, response?}}. Auto-generated during scenario generation when the agent has mock tools attached; can also be set or edited manually."
    },
    "folder_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Path of an existing folder to assign this evaluator to, e.g. \"Sales\" or \"Sales.Inbound\". Create it first with the create-folder endpoint."
    },
    "max_duration": {
      "type": [
        "integer",
        "null"
      ],
      "description": "\nMax call duration in seconds for this scenario. If not provided or set to null, the scenario will use the project's max_call_duration setting.\nValid range: 10-3600 seconds (10 seconds to 60 minutes)\nExample: `600` (10 minutes)\n"
    }
  },
  "required": [
    "personality"
  ],
  "$defs": {
    "AIAgentTestProfile": {
      "type": "object",
      "description": "",
      "properties": {
        "id": {
          "type": "integer",
          "readOnly": true
        },
        "project": {
          "type": [
            "integer",
            "null"
          ]
        },
        "agent": {
          "type": [
            "integer",
            "null"
          ]
        },
        "agent_name": {
          "type": "string",
          "readOnly": true,
          "description": "\nName of the agent associated with this test profile\nExample: `\"Customer Support Agent\"`\n"
        },
        "name": {
          "type": "string",
          "maxLength": 255
        },
        "information": {
          "description": "\nVariables for the test profile, split by which agent receives them.\n```json\n{\n    \"main_agent_variables\": {\"user_id\": \"U-123\"},\n    \"testing_agent_variables\": {\"user_name\": \"John Doe\", \"user_email\": \"john.doe@example.com\"}\n}\n```\n`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.\n\nKeys in `main_agent_variables` starting with `X-` are additionally sent as custom SIP headers (SIP runs) or connection headers (WebSocket runs) to the agent under test. For SIP runs this is the only way to pass custom headers; `X-Run-Id`, `X-Scenario-Id`, and `X-Result-Id` are reserved and always set by Cekura.\n"
        },
        "created_by": {
          "type": [
            "integer",
            "null"
          ],
          "readOnly": true,
          "description": "ID of the user who created this test profile"
        },
        "last_updated_by": {
          "type": [
            "integer",
            "null"
          ],
          "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"
      ]
    },
    "PhoneNumberInbound": {
      "type": "object",
      "description": "",
      "properties": {
        "id": {
          "type": "integer",
          "readOnly": true
        },
        "number": {
          "type": "string",
          "maxLength": 15
        },
        "phone_number_id": {
          "type": "string",
          "maxLength": 255
        }
      },
      "required": [
        "number",
        "phone_number_id"
      ]
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/cekura-ai-scenario-serializer-v2"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.