Quickstart

Create an object definition and publish its first state.

Define the object

Create a named JSON resource that describes the state BigState will accept.

Publish state

Write a timestamped value and receive the version assigned by BigState.

What you will build#

This example creates one object:


quickstart:counter@YOUR_OWNER

It then publishes this JSON state:


{
	"value": {
		"count": 1
	}
}

The object definition is the stable contract and configuration. State is the changing, versioned value associated with that object.

Before you begin#

You need your owner identifier and an API key that can create objects and set state.

If you do not have these values yet, follow Create an account and save your credentials.

Run this example in a trusted environment

The requests use an API key that can write data.

Keep the key out of browser code and source control.

Create the project#

No project or SDK. Run the curl commands below from a terminal.

Initialize the client#

BIGSTATE_OWNER identifies your namespace and becomes part of the object name. BIGSTATE_API_KEY is sent as x-api-key on each request.

Each curl command carries the API key itself. There is no client object to create.

Publish the first state#

The shortest path is to set object state. If the object does not exist, BigState creates it and stores the value as its first state.


curl -X POST "https://api.bigstate.dev/v1/state?object=quickstart%3Acounter%40YOUR_OWNER" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"at\":\"2026-04-24T12:00:00Z\",\"value\":{\"count\":1}}"

A successful response is 200 and includes the action and the new version:


{ "action": 1, "version": 1 }

You can also include an object definition in the body when you need to control its type, lifetime, validity, version history, or descriptive metadata. Use the flow below when object configuration should stay a separate request.

See Set object state for all publication modes, request fields, and response parameters.

Create the object separately#

For explicit provisioning, create or update an object before publishing any state. type 2 is JSON. See request parameters.


curl -X POST "https://api.bigstate.dev/v1/object?object=quickstart%3Acounter%40YOUR_OWNER" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"type\":2,\"ttl\":86400,\"validity\":60,\"versionDeep\":10,\"info\":{\"name\":\"Quickstart counter\",\"desc\":\"Counter created by the REST quickstart\",\"example\":{\"count\":1}}}"

The create-or-update call creates the definition when the name is new and updates it when the same name already exists. A successful response is 200 with "action": 1 when the object is created.

The definition controls how BigState handles this object's state:

type — the encoding expected for state values; 2 is JSON.
ttl — the lifetime of the object and its related data, in seconds.
validity — how long a state is considered current, in seconds.
versionDeep — how many previous state versions BigState retains.

The info fields describe the object for people reading its configuration. They are not the current counter state. This separate operation is useful when resource provisioning and state publication belong to different application stages or services.

See Create or update an object for the complete object definition and supported field values.

Publish state to the existing object#

After the object exists, publish state without repeating the definition. The object name selects the object. at records when the publisher produced the value, and value contains the JSON data accepted by the definition.


curl -X POST "https://api.bigstate.dev/v1/state?object=quickstart%3Acounter%40YOUR_OWNER" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"at\":\"2026-04-24T12:00:00Z\",\"value\":{\"count\":1}}"

In the two-request flow, the object must exist before you publish state to it. Each successful publication receives its own version number.

To inspect the result afterward, use Get object state or List object versions.

Run#

Run any curl command above. A successful first publish returns HTTP 200:


{ "action": 1, "version": 1 }

Action 1 means created. Running either flow again can return action 2 and a higher version.

Next steps#

Authentication Deliver and read state

What you will build
Before you begin
Create the project
Initialize the client
Publish the first state
Create the object separately
Publish state to the existing object
Run
Next steps