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/:id

Runs

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/web

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

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/:id

These map to the create_simulation, step_simulation, run_web_simulation, and scenario MCP tools. Full schemas are in the OpenAPI reference.