Simulation API
Read, configure, reset, advance, message, book, cancel, and resolve the world.
Simulation state
| Route | Body | Result |
|---|---|---|
GET /api/simulation | — | Complete persisted SimulationState |
PATCH /api/simulation | { config?, running? } | Updated complete state |
POST /api/simulation | { config? } | Newly seeded complete state |
Patch requests merge top-level configuration and nested transport fields. Reset requests merge the provided configuration over defaults, validate it, and replace the world.
curl -X PATCH http://localhost:3000/api/simulation \
-H 'Content-Type: application/json' \
-d '{"running":false}'Advance time
POST /api/simulation/tick accepts { "steps": 1 }. Steps default to 1 and must be between 1 and 24.
Each step flushes already queued substrate work, ticks the world, resolves pending AI decisions when enabled, flushes work created by those decisions, and then drains eligible tasks.
Inject work
Messages
POST /api/simulation/messages accepts an incoming message draft. It queues the message; delivery occurs when a tick reaches its optional deliverAfter.
Appointment requests
POST /api/simulation/appointments accepts a booking request draft and immediately flushes the booking substrate.
Cancellation requests
POST /api/simulation/appointments/cancel accepts an appointment id, optional source, and optional reason, then immediately flushes cancellation work.
{
"profileId": "profile_…",
"organizationId": "north-star",
"source": "practice-api",
"kind": "follow-up",
"urgency": "soon",
"reason": "Review response to medication",
"preferredWindow": {
"earliestAt": "2026-07-21T08:00:00.000Z",
"latestAt": "2026-07-23T17:00:00.000Z",
"note": "Afternoons preferred"
}
}Resolve decisions
POST /api/simulation/organic supports two shapes.
{
"requestId": "decision_…",
"evaluator": "ai"
}{
"requestId": "decision_…",
"evaluator": "human",
"action": "send-message",
"messageBody": "I have moved this to the urgent review queue.",
"note": "Symptoms need same-day assessment.",
"followUpTask": {
"title": "Assess symptoms",
"description": "Review the update and call the patient.",
"priority": "urgent",
"dueInMinutes": 30
},
"stressDelta": -0.05
}