POSTTest onlysimulation:write

Create scenario run

Run a preset scenario by ID or a custom timeline.

Request

POSThttps://api.cymatics.tech/v1/scenario-runs

Send your key as Authorization: Bearer cym_test_…. Requires the simulation:write scope. Test mode only: live keys get 403 mode_mismatch.

Idempotency-Keystring headerReplays the first response for an identical request within the project and mode.

Request body

Either PresetScenarioRun

`scenario_id`requiredstring	body
`speed`number, > 0 and ≤ 3600	body
`seed`integer	body

Or CustomScenarioRun

`timeline`requiredobject	bodyA scripted test timeline. Step times are milliseconds after start_time.
`speed`number, > 0 and ≤ 3600	body
`seed`integer	body

application/json

{
  "scenario_id": "bed_exit",
  "speed": 1,
  "seed": 42
}

Response

201 · application/json

{
  "data": {
    "object": "scenario_run",
    "id": "run_01",
    "scenario_id": "bed_exit",
    "status": "running",
    "elapsed_ms": 0,
    "duration_ms": 60000,
    "speed": 1,
    "seed": 42,
    "rooms": [
      {
        "id": "room_bedroom"
      }
    ],
    "devices": [
      {
        "id": "dev_bedroom",
        "room_id": "room_bedroom"
      }
    ]
  },
  "meta": {
    "request_id": "req_01",
    "project_id": "proj_demo",
    "livemode": false,
    "generated_at": "2026-10-24T23:55:30.000Z"
  }
}

Errors

429rate_limit_exceeded: Too many requests this minute for the key (or twice that across the project), or too many open streams for the project. Retry after the seconds in Retry-After.quota_exceeded: A live key's project has used its monthly live-hour cap. There is no Retry-After. Don't retry; raise the live-hour cap in the dashboard. Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.
503live_unavailable: This operation has no live data for this project yet (for example, no paired Cymo covers it). Don't retry the same request; pair a Cymo that covers it, or build against a test key.service_unavailable: A dependency, such as API key verification, is unreachable, or the project is busy with another write. Retry after the seconds in Retry-After, with backoff.
4XXInvalid request, credential, permission or revision.
defaultError with a stable code and request ID.

Every error is a { error, meta } envelope with a stable code. See Errors for each code and whether to retry.

Call it

TypeScript · @cymos/sdk

import { Cymo } from "@cymos/sdk";

const cymo = new Cymo({ apiKey: process.env.CYMO_API_KEY! });

const { data, meta } = await cymo.scenarioRuns.create({
  scenario_id: "bed_exit",
  speed: 1,
  seed: 42
});

terminal · cymatics CLI

$ cymatics scenarios run --input body.json --json

curl

curl -X POST "https://api.cymatics.tech/v1/scenario-runs" \
  -H "Authorization: Bearer $CYMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario_id":"bed_exit","speed":1,"seed":42}'

The SDK takes path parameters and body fields in one object. The CLI reads the body from --input, a JSON file or - for stdin.

MCP tool

create_scenario_run({
  input: {
    scenario_id: "bed_exit",
    speed: 1,
    seed: 42
  }
})

The MCP tool create_scenario_run calls this operation with your key. It takes the request body as input.