Skip to main content
POST
Add a state (node)

Authorizations

Authorization
string
header
required

An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).

Headers

If-Match
string

The rev you last read. Mismatch returns 409.

Path Parameters

id
string<uuid>
required

Body

application/json
id
string
base
string
camera
object

A static/dynamic prompt pair. The world model is conditioned on the static layer while the scene holds and on the dynamic layer while it moves. Both are pixel-prose, never authorial intent.

movement
object

A static/dynamic prompt pair. The world model is conditioned on the static layer while the scene holds and on the dynamic layer while it moves. Both are pixel-prose, never authorial intent.

ambient
string[]
ending
object
variants
object[]
expectedRev
string

Alternative to the If-Match header.

Response

State added

The result of a graph write. world is the new, kernel-validated world; diagnostics carries advisory (warning/info) findings; rev is the new concurrency token (also returned as the ETag header).

world
object

A playable world's compiled graph, id, name, entrance, and the scene (states + events). This is the shape returned inside the world field of a World resource (see World) and by the graph-editing routes. Additional optional properties are allowed (forward-compatible); the schemaVersion on responses pins the contract version.

diagnostics
object[]
rev
string

The new revision token. Pass it as If-Match on the next write.

schemaVersion
string
Example:

"1.0"

stateId
string