Sim Engine

The Sim Engine lets you create business simulations where a company and world co-evolve turn by turn. You can branch scenarios, apply external world events, have agents debate each decision, and generate a final strategy report.

Token cost: Simulation creation and turn advancement require significantly more AI tokens than other endpoints. Ensure your account has sufficient token balance before calling these endpoints at scale.

Create a new business simulation. Provide a company baseline and choose the turn unit (quarter or year). The simulation starts at turn 0 with no states; call /advance to run the first turn.

Request body

Name	Type	Required	Description
`name`	`string`	required	Human-readable simulation name
`description`	`string`	optional	Optional context or objective for this simulation
`turnUnit`	`string`	required	"quarter" \| "year" — time unit per simulation turn
`companyBase`	`object`	required	Baseline company state: { revenue, employees, burn, sector, ... }

Response

{
  "simulation": {
    "id": "sim_abc",
    "name": "Scale scenario 2026",
    "turnUnit": "quarter",
    "currentTurn": 0,
    "companyBase": { "revenue": 500000, "employees": 12, "burn": 80000 },
    "createdAt": "2026-06-01T09:00:00Z"
  }
}

curl -X POST https://api.yourdomain.com/v1/sim-engine/simulations \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Scale scenario 2026",
    "description": "Modelling two growth paths for next fiscal year",
    "turnUnit": "quarter",
    "companyBase": {
      "revenue": 500000,
      "employees": 12,
      "burn": 80000,
      "sector": "B2B SaaS"
    }
  }'

List all simulations in your workspace.

Response

{
  "simulations": [
    {
      "id": "sim_abc",
      "name": "Scale scenario 2026",
      "currentTurn": 3,
      "turnUnit": "quarter",
      "createdAt": "2026-06-01T09:00:00Z",
      "_count": { "states": 3 }
    }
  ]
}

Get a full simulation including scenarios and the most recent states.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Simulation ID

Response

{
  "simulation": {
    "id": "sim_abc",
    "name": "Scale scenario 2026",
    "companyBase": { "revenue": 500000, "employees": 12 },
    "scenarios": [ { "id": "scen_1", "name": "Conservative" } ],
    "states": [ { "turn": 1, "companyState": { ... }, "worldState": { ... } } ]
  }
}

Add a named scenario (world parameter set) to a simulation. Multiple scenarios let you run parallel what-if branches.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Simulation ID

Request body

Name	Type	Required	Description
`name`	`string`	required	Scenario name (e.g. "Recession baseline")
`description`	`string`	optional	Optional scenario description
`parameters`	`object`	optional	World parameter overrides for this scenario

Response

{
  "scenario": {
    "id": "scen_xyz",
    "simulationId": "sim_abc",
    "name": "Recession baseline",
    "isActive": true,
    "createdAt": "2026-06-01T10:00:00Z"
  }
}

Run one turn of the simulation. Agents debate the state, world events are applied, and the company evolves. Returns the new state snapshot for each active scenario.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Simulation ID

Response

{
  "states": [
    {
      "id": "state_1",
      "turn": 1,
      "companyState": {
        "revenue": 530000,
        "employees": 14,
        "burn": 85000
      },
      "worldState": { "gdpGrowth": 0.024, "inflationRate": 0.031 },
      "events": [ { "label": "Competitor raised Series B", "impact": "medium" } ]
    }
  ]
}

Get the final AI-generated strategy report. Only available after the simulation has been advanced to completion and finalized. Returns 404 if no report exists yet.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Simulation ID

Response

{
  "report": {
    "summary": "Over 4 quarters, revenue grew 26%...",
    "keyDecisions": [ "Hired 2 engineers in Q2", "Deferred Series A to Q4" ],
    "risks": [ "CAC increased 18% in Q3" ],
    "recommendations": [ "Prioritise retention before next growth push" ]
  }
}

Permanently delete a simulation and all its states. Returns 204 No Content.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Simulation ID