State
State is the current value of an object—timestamped and versioned each time you publish. The object definition is the stable contract; state is what changes. Publishers write state over HTTP; deliveries can push matching updates to subscribers, and any client can always re-fetch the latest or a historical version when it needs the authoritative value.
Each successful set creates a new version. How many past versions you keep depends on the object’s versionDeep. For large or binary payloads, upload a value first and publish with valueRef instead of an inline body.
How you publish#
Choose exactly one update mode per set request:
value
Replace the state with an inline payload that matches the object type.
valueRef
Replace the state by referencing a previously uploaded binary value.
mutation
Patch a JSON object or increment a number without sending the full value.
Do not combine these modes in one request. Inline values follow the object’s type: JSON object, number, string, or Base64 binary.
How you read#
- Latest — get state for an object with no version parameter
- Specific version — pass
versionwhen you need a past snapshot - Many objects — list states with an optional name pattern and pagination cursor
A common app pattern is: read the latest state on startup, then subscribe over WebSocket delivery for subsequent updates.
When to use these endpoints#
- Set state whenever a publisher has a new value (or a patch / increment)
- Get state to load the current or a historical snapshot
- List states to scan many objects’ latest snapshots by pattern
- Use List versions when you need the version timeline before fetching one snapshot
Define the object first (or include a definition with an inline value on set). See the JavaScript quickstart.