Simulations API
Simulations exercise an agent with a scripted caller so you can test behavior before (or instead of) a real conversation. Runs persist as normal conversations. Reading is gated on simulations.read; writing on simulations.write.
Scenario templates
Save a reusable customer-side goal for repeated runs.
GET /api/v1/rest/simulation-scenarios
POST /api/v1/rest/simulation-scenarios
{
"name": "Asks for a manager",
"prompt": "You are a caller who wants to escalate to a manager.",
"acceptance_criteria": "Agent offers to transfer to a human."
}
GET /api/v1/rest/simulation-scenarios/:id
PATCH /api/v1/rest/simulation-scenarios/:id
DELETE /api/v1/rest/simulation-scenarios/:idRuns
GET /api/v1/rest/simulations ?widget_id= &status=
POST /api/v1/rest/simulations
{
"opponent_widget_id": "uuid", // the agent under test
"scenario_text": "Caller wants Saturday service hours.",
"widget_id": "uuid", // optional caller agent; omit for the built-in caller
"tool_mode": "mock", // mock | live | sandbox
"surface": "web" // web | phone
}Drive a turn-based run with POST /api/v1/rest/simulations/:id/step until it completes, then read the transcript with GET /api/v1/rest/simulations/:id.
Web-interaction test
POST /api/v1/rest/simulations/webRuns the agent's widget on its real site in a headless browser, driven by a simulated visitor — synchronous, up to 5 minutes, recorded as a normal conversation.
Live writes are refused by default
POST /simulations/web, /simulations/phone and /simulations/campaign, and POST /simulations or /simulations/:id/rerun with tool_mode: "live", run the agent's real integrations, and an integration that is not in test mode writes real records even during a simulation. So these routes answer 409, with code: "live_writes_refused" and the integrations at fault, when the agent under test has a write-capable integration that is not mocked. They answer 503 (safety_check_failed) if its integrations cannot be read. mock and sandbox text runs are not checked.
For a deliberate live run, say so on that call:
{
"allow_live_writes": true,
"live_writes_reason": "Why this run may write, and whose permission it has"
}The reason is required (10 to 500 characters) and is recorded in the audit log as simulation.live_writes_override, in your workspace and in the workspace that owns the agent. The create_simulation, rerun_simulation, run_web_simulation, run_phone_simulation and run_campaign_simulation MCP tools take the same two fields.
A campaign run checks the agent on every phone stage, because a move into a later stage can place a call. On another workspace's agent the refusal names no integrations, and the override answers 403 unless your workspace is its parent or you can run simulations there.
Manage a run
POST /api/v1/rest/simulations/:id/cancel # cancel an in-flight run
POST /api/v1/rest/simulations/:id/rerun # clone the config into a fresh run
DELETE /api/v1/rest/simulations/:idThese map to the create_simulation, step_simulation, run_web_simulation, and scenario MCP tools. Full schemas are in the OpenAPI reference.