Deliver and read state

Receive state over WebSocket delivery, or read the latest and a specific version over HTTP.

Choose a state access model#

BigState stores state independently from its delivery configuration:

• Use WebSocket delivery when a dashboard, browser, or service must react to changes continuously.
• Use the latest-state request when loading a page, restoring application state, or checking the current value on demand.
• Use a versioned request when you need one previously recorded state.

A common application combines both models: read the latest state during startup, then subscribe for subsequent updates.

Before you begin#

You need an existing object with published state, your owner identifier, and credentials that can access that object.

If you have not published state yet, complete the Quickstart.

Configure a WebSocket delivery#

A delivery selects which object updates to send. Create a delivery once. type 1 is WebSocket. A successful call returns 204 and an empty body.

curl -X POST "https://api.bigstate.dev/v1/delivery?delivery=deliveryWsQuickstart" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"name\":\"Quickstart WebSocket delivery\",\"type\":1,\"objects\":[\"quickstart:counter@YOUR_OWNER\"]}"

objects determines which updates match this delivery. This example uses one fully qualified object name; delivery configurations can also use supported object patterns.

See Create or update a delivery for all delivery types, fields, and response codes.

Receive dynamic updates over WebSocket#

Connect to WebSocket delivery at wss://ws.delivery.bigstate.dev/v1 and authenticate with the API key. After the socket opens, send delivery.listen for the delivery id. The connection does not reconnect on its own.

wss://ws.delivery.bigstate.dev/v1?apiKey=YOUR_RESTRICTED_API_KEY

{
	"type": 2,
	"payload": {
		"command": "delivery.listen",
		"args": "deliveryWsQuickstart"
	}
}

The first callback, or a frame with type 1, carries state. The second callback, or a frame with type 4, carries errors. Send delivery.listen again for each additional delivery id.

Incoming messages#

The server pushes JSON frames. Check type, then read payload:

• State (1) — an object event. payload contains action, owner, object, and, when applicable, state.
• Error (4) — a connection or server error. payload may include code, description, and error.

A delivered state frame has this structure:

message
└── payload
    ├── object
    └── state
        ├── at
        ├── version
        └── value

One delivery can match multiple objects, so applications can inspect payload.object when they need to route updates.

See Connect to WebSocket delivery for the full protocol.

Read the latest state over HTTP#

Use get object state when you need the current value immediately rather than waiting for the next delivery.

curl "https://api.bigstate.dev/v1/state?object=quickstart%3Acounter%40YOUR_OWNER" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

A successful response is 200. The body includes the object name, owner, timestamps, version, encoding type, and either value or valueRef.

Read a specific state version#

Pass version on the same get object state request. List object versions when you do not know the number.

curl "https://api.bigstate.dev/v1/state?object=quickstart%3Acounter%40YOUR_OWNER&version=3" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

curl "https://api.bigstate.dev/v1/version?object=quickstart%3Acounter%40YOUR_OWNER" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

See Get object state for latest and versioned reads, and List object versions for the version-history response.

Next steps#