Set object state

State is a timestamped and versioned value associated with an object. It can be stored inline or refer to uploaded binary data through a valueRef, and consumers can read the latest version or a specific historical one.

Write the current state of an object. Choose exactly one update mode:

Inline replacement — send value.
Referenced replacement — send valueRef for a previously uploaded binary value.
Mutation — send mutation.patch to merge a partial JSON object, or mutation.incrementBy to change a numeric value.

Do not combine value, valueRef, and mutation. An inline value must match the object's configured type: 2 — JSON object, 3 — number, 4 — string, 5 — Base64 binary string. Type or mutation errors are best diagnosed by checking the definition with Get an object.

Use ttl to set the lifetime of this state row in seconds. You may also include an object definition with an inline value to create the object and its initial state in one request. Read the result with Get object state; upload binary bytes first with Upload a value when using valueRef.

Choose one update mode

Replacement and mutation payloads are mutually exclusive.

Send exactly one of value, valueRef, or mutation, and send only one mutation field.

POST

{{host}}/v1/state?object={{object}}

VERB:POST

BASE URL:{{host}}/v1/state

QUERY STRING:?object={{object}}

Query parameters#

RequiredOptional

objectstring
Required
Unique name of the object in the URL.
format:
abc:0-9@owner

Headers#

RequiredOptional

Send these headers with the request. Names are case-insensitive per HTTP rules.

x-api-keyRequired
Your BigState API key.
{{apiKey}}
Content-TypeRequired
MIME type of the request body.
application/json
AcceptRequired
MIME types the client can understand in the response.
application/json

Need a session token? See Token sign in.

Request body#

Inline value + timestamp (optional ttl)


{
  "at": "2023-04-24T20:15:10",
  "value": {
    "lat": 32.0,
    "lng": 12.0
  },
  "ttl": 600
}

Reference payload


{
  "at": "2023-04-24T20:15:10",
  "valueRef": "tjbpSRURRkJbPIrp9fGQuOYRVFg4gr5gf4BK2rVT"
}

Create object and set state


{
  "object": {
    "type": 2,
    "info": {
      "name": "{{owner}} garage position",
      "desc": "Contains information about position",
      "example": { "lat": 32.0, "lng": 12.0 }
    }
  },
  "at": "2023-04-24T20:15:10",
  "value": {
    "lat": 32.0,
    "lng": 12.0
  }
}

JSON object — value only (object must exist)


{
  "value": {
    "lat": 32.0,
    "lng": 12.0
  }
}

Mutate state — patch (partial JSON)


{
  "at": "2023-04-24T20:15:10",
  "mutation": {
    "patch": {
      "lat": 34.0
    }
  },
  "ttl": 60000
}

Mutate state — incrementBy (numeric value)


{
  "at": "2023-04-24T20:15:10",
  "mutation": {
    "incrementBy": 1
  },
  "ttl": 60000
}

Request parameters#

RequiredOptional

atstring
Optional
Timestamp for this state update (ISO 8601).
ttlnumber
Optional
Optional. Time-to-live for this state row, in seconds.
example: 600
mutationobject
Optional
Update existing state without sending a full replacement: mutually exclusive with `value` and `valueRef`. Send exactly one inner field — **`patch`** or **`incrementBy`** — not both.
Values
- patch — partial JSON object merged into the current value (JSON object / type 2)
- incrementBy — number added to the current numeric value (type 3)
- mutation.patchany
  Optional
  Fields to merge into the current JSON object state.
- mutation.incrementBynumber
  Optional
  Delta applied to the current numeric state.
  example: 1
valueany
Optional
Full replacement payload when `mutation` is not used. Mutually exclusive with `valueRef` and with `mutation` — send exactly one of value, valueRef, or mutation.
Values
- 2 — JSON object
- 3 — number
- 4 — string
- 5 — Base64 binary data
valueRefstring
Optional
Reference payload when `mutation` is not used. Mutually exclusive with `value` and with `mutation`.
objectobject
Optional
Optional. With `value`, creates the object if missing (same shape as POST /v1/object) and sets state in one call. Not used with `mutation`.

Response parameters#

200Response body · object
State was written (and optionally the object was created). Returns the new state version number.
```
{
  "action": 2,
  "version": 43
}
```
- actionnumber
  Indicates what happened.
  Values
  1 — created
  2 — updated
- versionnumber
  Version number assigned to the state you just wrote.
  example: 43
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
400Response body · object
Bad request.
```
{
  "error": 6,
  "desc": "Object must be formatted as object"
}
```
- errornumber
  Numeric error code. Use the response `desc` field for the human-readable explanation.
- descstring
  Human-readable description of the error.

Examples#

Set object state (inline value)

Write state with a timestamp, JSON `value`, and optional `ttl` (seconds) for an existing object.


curl 'https://api.bigstate.dev/v1/state?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "at": "2023-04-24T20:15:10",
  "value": {
    "lat": 32,
    "lng": 12
  },
  "ttl": 600
}'

Set object state (patch)

Merge a partial JSON object into the current value; optional `ttl`. Mutually exclusive with `value` / `valueRef`.


curl 'https://api.bigstate.dev/v1/state?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "at": "2023-04-24T20:15:10",
  "mutation": {
    "patch": {
      "lat": 34
    }
  },
  "ttl": 60000
}'

Set object state (`incrementBy`)

Add to the current numeric state; optional `ttl`. Mutually exclusive with `value` / `valueRef`.


curl 'https://api.bigstate.dev/v1/state?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "at": "2023-04-24T20:15:10",
  "mutation": {
    "incrementBy": 1
  },
  "ttl": 60000
}'

State Get state

Description
Query parameters
Headers
Request body
Request parameters
Response parameters
Examples