Reference
Control plane
Beside the vendor’s API, every simulator serves a control plane under /_rystic/. It loads scenarios, seeds and reads state, moves the clock, injects faults and resets. The control plane reference has each route’s methods, parameters and responses, and rystic help control-plane prints it for the CLI you have installed.
Control routes take no vendor API key. With an admin token set, they need only that token: The admin token.
Features
Each control route belongs to one feature, or to none. Plans and API keys says which plan grants which feature.
| Feature | Unlocks |
|---|---|
| none | version, routes, reset, docs with its sections, features and changelog; /_feed |
state_view | inspect, registers, egress, calls, ws, events, settle, actions, config; eval and its ledger, results, snapshot and evidence |
state_set | seed, credentials, clock, seed-rng, inject, egress-retain, webhooks, replies; every other eval path: advance, calibrations, claim, complete, episode, evaluators, policy and reference |
scenarios | scenarios, scenario |
faults | network, ws-drop, revoke, duplicate-delivery, page-cap |
ui | ui, the state UI; swagger and graphiql |
replay | the tape player routes under /_replay/, for tapes and the live feed (Kalshi → Replay a captured market day, Live feed) |
Three routes are gated another way. A signed file URL and a staged upload are gated by their signatures, and activity responds only to a caller on the same machine.
A reset disarms revoke, duplicate-delivery and page-cap, and each route’s entry gives the body that disarms it sooner.
POST /_rystic/reset returns the simulator to its built-in records. With {"to": "boot"} it restores the boot scenario, seed files, inject schedule and network profile again at the starting clock, which is what rystic reset posts. If the plan no longer includes one of those boot inputs, it returns 403 and changes nothing. /_rystic/version lists the targets a simulator takes as reset_to.
Boot configuration → Boot inputs says which feature each boot input needs.
Status codes
A route outside the simulator’s grant (Features by plan) returns 403 before it reads the method or the body, with an Unentitled body naming the feature it needs. A path no route names returns 404, and so does a route this simulator does not serve, such as the tape player on a simulator without tapes. A method a route does not take returns 405, so a browser prefetch of GET /_rystic/reset wipes nothing. Each route’s entry lists every status it returns.
A route that takes a fixed body (clock, credentials, scenario, network, egress-retain, page-cap, duplicate-delivery, revoke, ws-drop, seed-rng) still runs a request that includes a top-level key it doesn’t take. It names that key in an X-Rystic-Warning response header, in the simulator’s log and as an unknown-key control event on /_rystic/events. credentials and revoke show each unknown key as <redacted>, since one may be a credential. /_rystic/seed keeps ignoring a scenario file’s other keys.
curl -si -X POST localhost:$PORT/_rystic/clock -d '{"advance_seconds":60,"advance":60}' | grep -iE '^HTTP/|x-rystic-warning'
# -> HTTP/1.1 204 No Content
# -> X-Rystic-Warning: unknown key "advance" (keys: time, advance_seconds, wall_offset_seconds, advance_to_dues_within_ms)
A vendor path or method the simulator does not serve gets the vendor’s own refusal where the simulator models one, and otherwise 404 with {"message":"No route in twin for <METHOD> <path>"}.
Routes by plan
Each route’s entry in the control plane reference names the feature it needs, and Features groups the routes by feature. Features by plan says which plan includes which feature.
Discovering routes and scenarios
A running simulator lists its HTTP routes at GET /_rystic/routes: the vendor’s, and its own /_ routes such as Stripe’s POST /_dispute. It leaves out WebSocket endpoints, the /_rystic/ routes, /_feed and the tape player; Features lists the last three. It lists its named scenarios at GET /_rystic/scenarios and reports the reference version it serves as contract on GET /_rystic/version. Installation → Discover what a simulator can do lists what the CLI tells you.
API explorers
Observing → API explorers covers Swagger UI at /_rystic/swagger and Linear’s GraphiQL. The control plane’s spec there names the simulator’s own scenarios, views and registers, and adds its own /_ routes.
Concepts on other pages
Timelines
Timelines covers the event schedule, response bindings and a worked example.
Network profiles and fault injection
Network profiles and fault injection covers the profile format, its lifetime and the boot values.
Worked example: throttle Stripe charges with 429s
Network profiles → Throttle Stripe charges.
Boot inputs
Boot configuration covers what a simulator starts with and which inputs need a feature.
Environment variables
Boot configuration lists every variable and flag the binary reads.
What each plan boots
Boot configuration → Boot inputs covers what a simulator boots, and What reset does what a reset keeps.