Simulation, scenarios, and events

Simulation endpoints let a generated company evolve over time and expose an event stream that another application can consume.

Base path:

/api/v1/demo-jobs/{job_ref}

Start simulation

POST /api/v1/demo-jobs/{job_ref}/simulation/start

Body:

{
  "seed": 42,
  "start_date": "2026-01-01",
  "dials": {
    "chaos": 0.1,
    "fraud": 0.0
  }
}

If simulation exists, returns current state.

Get simulation status

GET /api/v1/demo-jobs/{job_ref}/simulation/status

Returns simulation clock, dial config, pause/resume state, and autonomous status.

Advance simulation

POST /api/v1/demo-jobs/{job_ref}/simulation/advance

Body:

{
  "days": 30,
  "hours": 0,
  "minutes": 0
}

Errors:

• 400 when the delta is not positive
• 400 when the delta exceeds the configured maximum advance window

Step simulation

POST /api/v1/demo-jobs/{job_ref}/simulation/step

Runs one simulation step.

Pause simulation

POST /api/v1/demo-jobs/{job_ref}/simulation/pause

Resume simulation

POST /api/v1/demo-jobs/{job_ref}/simulation/resume

Update dials

PATCH /api/v1/demo-jobs/{job_ref}/simulation/dials

Body:

{
  "trickle_rate": "10x",
  "fraud": 0.2,
  "chaos": 0.1
}

Create checkpoint

POST /api/v1/demo-jobs/{job_ref}/simulation/checkpoint

List checkpoints

GET /api/v1/demo-jobs/{job_ref}/simulation/checkpoints

Restore checkpoint

POST /api/v1/demo-jobs/{job_ref}/simulation/restore/{checkpoint_id}

List scenarios

GET /api/v1/demo-jobs/{job_ref}/scenarios

Returns scenario definitions available for the job/runtime.

Generate scenario suggestions

POST /api/v1/demo-jobs/{job_ref}/scenarios/generate

Use this to ask Fictix for scenario candidates appropriate to the company.

Inject simulation scenarios

POST /api/v1/demo-jobs/{job_ref}/simulation/scenarios

Body:

{
  "scenarios": [
    {
      "id": "ghost-employee",
      "params": {
        "months": 1
      }
    }
  ]
}

Returns or updates planted truth for the simulation.

Get scenario manifest

GET /api/v1/demo-jobs/{job_ref}/simulation/manifest

The manifest describes planted truth. Use it to build eval harnesses and to explain what the target application should have detected.

Delete scenario

DELETE /api/v1/demo-jobs/{job_ref}/simulation/scenarios/{scenario_id}

Removes a scenario when supported by the backend state.

List events

GET /api/v1/demo-jobs/{job_ref}/events

Query params:

Get event

GET /api/v1/demo-jobs/{job_ref}/events/{event_id}

Use events to:

• replay activity into another product
• inspect what simulation generated
• debug webhook delivery
• build eval timelines