API

designed · Phase 1 (#39) · PLAN §13.3 · Generated OpenAPI reference lands with #39; this page is the designed surface.

Base URL http://localhost:5000 (proxied as /api by the Vite dev server). JSON in and out. Tick numbers appear here and in the Studio only; the Viewer converts to world time.

Universes and ticking

Method	Path	Does
POST	/universes	create { config, scenario } → { id }
POST	/universes/{id}/worlds	add a world
POST	/universes/{id}/start · /pause · /resume	tick state machine: Running / Paused / Replaying / Stepping
POST	/universes/{id}/tick	advance one tick (step mode)
POST	/universes/{id}/speed	{ ticksPerSecond } — wall-clock only; never changes what a tick means
GET	/universes/{id}/state	current tick, state, world summaries

Systems

Method	Path	Does
GET	/universes/{id}/systems	active and inactive systems with per-system timing (the Studio's panel)
POST	/universes/{id}/systems/{name}/activate · /deactivate	hot-toggle at the next tick boundary; engine infrastructure is not listed

Graph

Method	Path	Does
GET	/worlds/{id}/graph	query by kind, component, area
GET	/worlds/{id}/entities/{nodeId}	full entity state + edges (incl. knows facts with derived confidence)
GET	/worlds/{id}/query	complex queries (all fires, hungry NPCs, …)

Player actions

Method	Path	Does
POST	/worlds/{id}/player-actions	queue actions → intents next tick; see Player actions for the body

Explain and history (the trace)

Method	Path	Does
GET	/worlds/{id}/explain/event/{eventId}?depth=6&breadth=3	causal chain for an event
GET	/worlds/{id}/explain/entity/{nodeId}	latest decision: winner, runners-up, inputs, provenance
GET	/worlds/{id}/history/{nodeId}?from&to	the entity's timeline in a world-time window
GET	/worlds/{id}/explain/change/{nodeId}/{attr}/{generation}	which intent wrote this value, from which source

Time travel

Method	Path	Does
GET	/worlds/{id}/snapshots	buffered range { from, to }
GET	/worlds/{id}/snapshots/{tick}	the graph at tick N (keyframe + replay)
POST	/worlds/{id}/rewind	{ tick } → Replaying from N
POST	/worlds/{id}/fork · DELETE /worlds/{id}/forks/{forkId}	Phase 3

Rules

POST/GET /worlds/{id}/rules, …/{ruleId}/activate, …/deactivate, DELETE — Phase 3.

Streams (SignalR)

Path	Carries
/worlds/{id}/events	real-time events, filterable by type, location, entity
/worlds/{id}/interest	per-tick interest score (chain depth/breadth) — the viewer auto-slows on it
/universes/{id}/events	universe-level events

Changes in Phase 1

Added history/{nodeId} and explain/change/...; snapshots/{tick} is reconstructed from keyframes; the Aspire-hosted layout is gone (two processes, PLAN §13.1).