Simulation and time

Simulation lets a Fictix company continue to change after initial generation. Use it when a static dataset is not enough.

Examples:

• advance a company clock
• generate new activity over time
• create webhook events
• plant scenarios
• inspect an event stream
• score whether another product found known issues

Simulation state

Every simulation has:

• a company/project id
• a clock
• a seed
• dial configuration
• autonomous status
• checkpoint history

Read status:

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

Starting simulation

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

Example body:

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

If simulation state already exists, the route returns the existing normalized state rather than creating a duplicate simulation.

Advancing time

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

Example:

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

The delta must be positive and within the configured advance limit.

Single step

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

Use step when you want one deterministic increment rather than a large time advance.

Pause and resume

POST /api/v1/demo-jobs/{job_id}/simulation/pause
POST /api/v1/demo-jobs/{job_id}/simulation/resume

Pause stops autonomous progression. Resume restarts it.

Dials

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

Example:

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

Dials control behavior intensity. Treat unknown dials as unstable unless they are documented in the catalog or scenario docs.

Checkpoints

Create checkpoint:

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

List checkpoints:

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

Restore checkpoint:

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

Use checkpoints for eval loops, demos, and repeatable QA.

Events

Read event feed:

GET /api/v1/demo-jobs/{job_id}/events?limit=50

Read one event:

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

Events are the bridge between simulation and host-product reactions. A future customer-facing integration can subscribe to webhooks, poll events, or both.

Scenario manifest

Scenario injection can plant truth into the company. The manifest describes what was planted.

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

Use the manifest for:

• test harness setup
• evaluating detected findings
• explaining what broke
• reproducing failed app behavior