Back to simulator RESOURCE

Session API

Native simulations run as isolated server processes. The browser controls them through REST endpoints and Server-Sent Events.

Authentication Model

Guests can create live simulations without signing in. Signed-in users send a Clerk session token as a Bearer token and get private saved runs, replays, and exports.

Authorization: Bearer <clerk-session-token>

Core Endpoints

MethodPathPurpose GET/api/health

Returns service status and active session count.

GET/api/auth/config

Returns Clerk browser configuration when auth is enabled.

POST/api/sessions

Creates a live simulation session.

GET/api/sessions/:id/events

Streams live or replayed simulation events through SSE.

DELETE/api/sessions/:id

Cancels an active native worker.

Create A Session

POST /api/sessions
Content-Type: application/json

{
  "seed": 42,
  "scheduler": "deterministic",
  "navigation": "bfs",
  "hunters": ["Ada", "Grace"]
}

The response includes the session id, event stream URL, replay URL, and whether the run was persisted.

Sharing And Exports

MethodPathPurpose GET/api/runs?limit=20

Lists signed-in user's private run history.

POST/api/runs/:id/share

Makes a completed run public.

DELETE/api/runs/:id/share

Revokes a public share token.

GET/api/shares/:token/events

Streams a public replay.

GET/api/runs/:id/export?format=json

Downloads a signed-in run export.

Operational Limits

Session creation is rate-limited per client address. Render Free should use a low worker count such as MAX_CONCURRENT_SESSIONS=2 and a timeout such as SESSION_TIMEOUT_MS=60000.