Simcraft execution APIv0.1.0

GET /v0/health#

Liveness and version.

Always returns ok: true with the server version. Use it to discover whether a Simcraft server is listening before offering remote execution.

Responses

GET /v0/libraries#

Registered component library definitions.

The library definitions (per spec/schemas/osdl.library.schema.json) registered in this server's engine, verbatim. A plugin distribution (see the Plugin API section of docs/contracts.md) reports its additional libraries here, which is how tooling such as the IDE palette discovers plugin components at runtime.

Responses

POST /v0/validate#

Validate a document without running it.

Validates one OSDL document for schema structure, semantic diagnostics, and buildability against the registered libraries. It never accepts execution options or starts a run. Returns 200 with the diagnostics array. An empty array means the document is valid.

Request body

Responses

POST /v0/runs#

Start a run.

Prepares the posted run before accepting it. Preparation validates the requested limits against server maximums, validates the OSDL document and selected experiment, applies parameter overrides, and builds the execution plan. A 201 response means the worker was created and the run is retained. Poll GET /v0/runs/{id} for completion and subscribe to GET /v0/runs/{id}/events for the live event stream.

The server has 128 run slots. Preparing requests, runs available through the status and event endpoints, and still-running workers deleted from lookup occupy these slots. Completed and failed runs keep their slot until deletion or expiry. A later POST removes completed or failed runs that have been retained for more than 3,600 seconds. Capacity does not evict a non-expired run.

Determinism: identical (document, experiment, parameters, seed, replication) produce byte-identical results, the same as a local CLI run. trace does not enter that tuple: it selects what the run streams, never what it computes.

Request body

Responses

GET /v0/runs/{id}#

Poll run status and results.

Returns the run's current state. Results appear in the shared results JSON shape after successful completion. Execution failures and caught worker panics produce status: error.

Parameters

Responses

DELETE /v0/runs/{id}#

Delete a run.

Removes the run from status and event lookup immediately. Deleting an active run does not cancel its worker. The worker keeps its run slot until it exits, and an event stream connected before deletion can continue until the worker exits. Deleting a completed or failed run releases its slot.

Parameters

Responses

GET /v0/runs/{id}/events#

Stream the typed event stream (WebSocket).

WebSocket upgrade. What the socket carries is fixed when the run is created. A run with trace off or collect streams sim.started, sim.progress, sim.completed, sim.error, sim.aborted, and param.changed only, at most 100 progress frames per replication, and its replay buffer holds a few thousand frames. A run with trace live streams every envelope it produces. There is no per-subscriber selection: the run decides, so every subscriber reads the same stream.

On connect the server replays the buffered envelopes, then streams live. The replay buffer is bounded to the newest 50,000 frames. A subscriber that connects late to an event-heavy run receives a trace that starts mid-run. Event seq values restart at 1 for each replication. A complete trace starts with run.scenario 0, run.replication 1, and seq 1. Any other first-envelope values identify a dropped prefix. Subscribers connected from the start miss nothing. Each envelope is one text frame of JSON per spec/schemas/osdl.events.schema.json. run.experiment, run.replication, and run.scenario are set on every event.

Normal execution finishes with a terminal sim.completed, sim.error, or sim.aborted frame. Multi-replication runs contain interior sim.completed frames, and the socket stays open across them. A caught worker panic records status: error but bypasses normal terminal-frame emission. The server then closes the socket with code 1000 and reason run completed.

A subscriber that falls behind the live broadcast is resynchronized from the replay buffer: the server resends only the frames that subscriber has not received, so its trace carries no gap and no duplicate. A subscriber that falls behind by more than the buffer retains cannot be resynchronized, and the server closes the socket with code 1008 and reason trace cut: replay buffer no longer covers this subscriber. Deleting the run does not close the sockets already streaming it; they run on until the run completes.

Parameters

Responses

POST /v0/sessions#

Start an interactive session.

Prepares one selected scenario and replication, creates its worker, and waits for the initial paused snapshot. A successful session starts at simulation time 0 with speed 1.0 on root branch b1. The default server retains at most 8 sessions and 32 branches per session through its maxBranches policy. Completed and errored sessions remain retained for 3,600 seconds unless deleted.

Request body

Responses

GET /v0/sessions/{id}#

Get an interactive session snapshot.

Parameters

Responses

DELETE /v0/sessions/{id}#

Delete an interactive session.

Removes the session from lookup and disconnects its worker.

Parameters

Responses

POST /v0/sessions/{id}/commands#

Control an interactive session.

Applies one tagged command and returns the immediate post-command snapshot. runTo, runToEnd, seek, and switchBranch targets that require replay return promptly with state playing; the worker advances in bounded bursts. A rebuilt seek to time zero returns state paused. Branch-switch replay finishes to the target tip. During that replay pause is a no-op, setSpeed, switchBranch, and stop apply, and every other command returns the unchanged snapshot with a transient error field. Observe asynchronous target arrival, completion, or failure through session.status frames or GET /v0/sessions/{id}. seek and switchBranch can rebuild a completed or errored session. Other commands return its final snapshot unchanged. Parameter-name, parameter-value, branch-id, and branch-limit validation failures return status 200 with the unchanged snapshot and a transient error field.

Parameters

Request body

Responses

GET /v0/sessions/{id}/events#

Stream interactive session events (WebSocket).

WebSocket upgrade. The server replays buffered simulation envelopes, then streams live simulation envelopes and session.status frames. Status frames are emitted on state, generation, or active-branch transitions and at a 100 ms cadence while state is playing, including turbo advancement. Status frames bypass the replay buffer, so late subscribers read GET /v0/sessions/{id} for the current snapshot. The buffer retains the newest 50,000 simulation event frames. Event seq restarts at 1 after a replay generation change. A live parameter edit keeps the generation and emits param.changed in the current trace. The socket stays open across completed and error states because seek and switchBranch can revive the session. It ends when the client disconnects or delivery fails, and closes with code 1000 and reason stream closed when the session is deleted or expires. A subscriber that falls behind the live broadcast is resynchronized from the replay buffer: the server resends only the event frames that subscriber has not received, so its trace carries no gap and no duplicate, but it does miss the status frames sent while it was behind. A subscriber that falls behind by more than the buffer retains cannot be resynchronized, and the server closes the socket with code 1008 and reason trace cut: replay buffer no longer covers this subscriber. Clearing the buffer, which seek backward and switchBranch do, cuts a subscriber that was still behind in the previous generation.

Parameters

Responses

GET /v0/runs/{id}/scenarios/{scenario}/replications/{replication}/events#

Fetch one replication's collected trace.

Returns the envelopes a single replication recorded during a collect run, as NDJSON. The first line is a header object carrying runId, scenario, replication, cap, envelopes, discarded, truncated, from and count; every line after it is one envelope. envelopes is the total the replication recorded and count is how many this response carries, so a client renders its position as from + 1 to from + count of envelopes. Truncation is reported before the payload it describes. One replication of the packaged M/M/1 example records about 80,000 envelopes and 17 MB, so a reader pages with from and limit rather than fetching a whole replication. Available once the run has finished. A run started off or live recorded nothing and answers 409.

Parameters

Responses