Skip to main content
POST
/
v1
/
create-simulation
Create Simulation
curl --request POST \
  --url https://api.getbluejay.ai/v1/create-simulation \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "agent_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "knowledge_base_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequential_calling": false,
  "max_concurrent": 250,
  "hangup_on_transfer": false,
  "max_call_duration": 10,
  "max_call_duration_units": "minutes",
  "ringing_timeout": 300,
  "digital_humans_settings": {
    "default_name": "random",
    "default_caller_number": "random",
    "default_language": "random",
    "default_background_noise": "none",
    "first_message": "ai_generated",
    "num_runs": 1
  },
  "selected_custom_metrics": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "custom_metrics_failing_threshold": 50,
  "custom_metrics_passing_threshold": 50,
  "always_on": false
}
'
{
  "simulation_id": 123,
  "status": "200"
}
Integration Prompt for AI Agents
# Bluejay — Testing & Monitoring Platform for Conversational AI Agents

You are a senior backend engineer integrating the Bluejay API. Think step-by-step: first understand the endpoint, then plan the integration, then implement with minimal changes.

## Create Simulation — POST /v1/create-simulation

> **What this endpoint does:** Create a new simulation with the provided details. Returns the simulation id and a status code.

**Endpoint:** POST `https://api.getbluejay.ai/v1/create-simulation`
**Auth:** `X-API-Key` header
**Content-Type:** application/json

### Required Parameters
| Name | Type | Description |
|------|------|-------------|
| X-API-Key | string | API key required to authenticate requests. |
| agent_id | string | ID of the agent to be used in the simulation |

Review the full parameter list at https://docs.getbluejay.ai/api-reference/endpoint/create-simulation and include any optional parameters (e.g., `name`, `description`, `prompt_id`, `knowledge_base_id`, `sequential_calling`, `max_concurrent`) that serve your integration's use case and align with Bluejay's testing and monitoring capabilities.

### Request Body (required fields)
```json
{
  "agent_id": "string"
}
```

Refer to the full schema at https://docs.getbluejay.ai/api-reference/endpoint/create-simulation. Include optional fields that serve the goal of setting up for testing and monitoring on Bluejay.

### Example
**POST with body:**
```python
import requests

def create_simulation(payload: dict, api_key: str) -> dict:
    url = "https://api.getbluejay.ai/v1/create-simulation"
    headers = {"X-API-Key": api_key}
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()
```

### Constraints
- Minimal changes — only add/change files needed for this integration.
- Match existing codebase patterns (naming, file structure, error handling).
- Include error handling for 422: Validation Error.

### Integration Checklist
Before writing code, verify:
1. Which module/service owns this API domain in the codebase?
2. What HTTP client and error-handling patterns does the project use?
3. Are there existing types/interfaces to extend?

Then implement the integration, export it, and confirm it compiles/passes lint.
Given the agent ID, and simulation settings, this endpoint creates a simulation and returns the simulation ID.

Headers

​
X-API-Key
string
required

API key required to authenticate requests.

Body

application/json

Pydantic model for simulation request

​
agent_id
string
required

ID of the agent to be used in the simulation

​
name
string | null

Name of the simulation

​
description
string | null

Description of the simulation

​
prompt_id
string<uuid> | null

Optional default prompt UUID for this simulation

​
knowledge_base_id
string<uuid> | null

Optional default knowledge base UUID for this simulation

​
sequential_calling
boolean | null
default:false
deprecated

Whether to run the simulation with sequential calling

​
max_concurrent
integer | null

Maximum number of concurrent calls in the simulation (max 500)

Required range: 0 < x <= 500
​
hangup_on_transfer
boolean | null
default:false

Whether to hang up the call on transfer

​
max_call_duration
integer | null
default:10

Maximum duration of each call (default is 10). Units specified by max_call_duration_units

​
max_call_duration_units
enum<string> | null
default:minutes

Units for max_call_duration: 'minutes' (default) or 'seconds'

Available options:
minutes,
seconds
​
ringing_timeout
integer | null
default:300

Ringing timeout in seconds for SIP trunks (default 300s)

​
digital_humans_settings
DigitalHumansSettings · object

Settings for digital humans in the simulation

​
selected_custom_metrics
string<uuid>[] | null

Custom metric IDs to enable for this simulation

​
custom_metrics_failing_threshold
integer | null

Score threshold below which a custom metric is considered failing (0-100)

Required range: 0 <= x <= 100
​
custom_metrics_passing_threshold
integer | null

Score threshold at or above which a custom metric is considered passing (0-100)

Required range: 0 <= x <= 100
​
always_on
boolean | null
default:false

When true, simulation has always-on digital humans configured

Response

Successful Response

​
simulation_id
integer
required

ID of the created simulation

​
status
string
default:200

Status of the response