Create Scenario

Create a simulation scenario from a dataset, script, or conversation graph. Supports AI graph generation, persona assignment, and custom columns. Returns 202 Accepted.

POST https://api.futureagi.com/simulate/scenarios/create/

Authentication

X-Api-Key API Key Required

Your Future AGI API key used to authenticate requests. You can find and manage your API keys in the Dashboard under Settings.

X-Secret-Key Secret Key Required

Your Future AGI secret key, used alongside the API key for request authentication. This is generated when you create an API key in the Dashboard.

Request body

name string Required

Name for the scenario. Max 255 characters. Cannot be blank or whitespace-only.

kind string Optional

Scenario type: "dataset" (default), "script", or "graph".

source_type string Optional

Source for AI-powered generation: "agent_definition" (default) or "prompt". When "prompt", both prompt_template_id and prompt_version_id are required.

description string Optional

Optional description of the scenario.

dataset_id string Optional

UUID of the source dataset. Required when kind is "dataset".

script_url string Optional

URL of the call script file. Required when kind is "script".

agent_definition_id string Optional

UUID of the agent definition to test. Required when generate_graph is true and source_type is "agent_definition".

agent_definition_version_id string Optional

UUID of a specific agent version. Defaults to the latest version.

generate_graph boolean Optional

Auto-generate a conversation graph from the agent definition or prompt template. Default: false.

graph object Optional

Conversation graph data. Required when kind is "graph" and generate_graph is false.

no_of_rows integer Optional

Number of test case rows to generate. Range: 10–20000. Default: 20.

add_persona_automatically boolean Optional

Automatically assign diverse personas to generated test cases. Default: false.

personas array of string Optional

List of persona UUIDs to include in the scenario.

custom_columns array of object Optional

Custom column definitions (max 10). No duplicate names allowed. Each column must have:

  • name (string, max 50 chars)
  • data_type (one of: text, boolean, integer, float, json, array, image, images, datetime, audio, document, others, persona)
  • description (string, max 200 chars)
prompt_template_id string Optional

UUID of the prompt template. Required when source_type is "prompt".

prompt_version_id string Optional

UUID of the prompt version. Required when source_type is "prompt". Must belong to prompt_template_id.

custom_instruction string Optional

Additional instruction to steer AI scenario generation.

voice_provider string Optional

Voice provider for simulator agent. Default: "elevenlabs".

voice_name string Optional

Voice name for simulator agent. Default: "marissa".

model string Optional

LLM model for simulator agent. Default: "gpt-4".

Response

202 Accepted
message string
Confirmation that scenario creation has been queued (e.g. "Dataset scenario creation started").
scenario object
Created scenario object (full ScenarioSchema — see List Scenarios for field reference).
status string
Always "processing" on initial response. Poll Get Scenario for the final status.

Errors

400 Bad Request Optional

Validation error. The response includes an error message and a details object with per-field errors.

{
  "error": "Invalid data",
  "details": {
    "dataset_id": ["dataset_id is required for dataset kind."],
    "custom_columns": ["Duplicate column name(s): col_name"]
  }
}

Common causes:

  • name is blank or whitespace-only
  • dataset_id missing when kind="dataset"
  • script_url missing when kind="script"
  • graph and generate_graph both absent when kind="graph"
  • prompt_template_id or prompt_version_id missing when source_type="prompt"
  • Duplicate column names in custom_columns
  • Persona column in source dataset has wrong data_type
401 Unauthorized Optional

Invalid or missing API credentials.

500 Internal Server Error Optional

Unexpected server error.

{"error": "Failed to create scenario: <message>"}
GET /
Authentication
REQUEST 
 
 
  
 
 RESPONSE