State set

Write subject state for an object. Either replace the payload (value or valueRef — mutually exclusive) or mutate with mutation: patch (partial JSON merged into JSON object state) or incrementBy (delta for numeric state) — do not send value / valueRef together with mutation. Inline value must match the object’s type: 2 — JSON object, 3 — number, 4 — string, 5 — Base64 binary (string). Optional ttl sets how long the state row remains valid, in seconds. You can combine value with an embedded object to create the object and set state in one request; for existing objects you can send value alone when appropriate.

POST

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

VERB:POST

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

QUERY STRING:?object={{object name}}

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.
*provide api key here*
Content-TypeRequired
MIME type of the request body.
application/json
AcceptRequired
MIME types the client can understand in the response.
application/json

See authentication headers here.

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": "{{owner1}} 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. See the error codes reference for the full list.
- descstring
  Human-readable description of the error.

Examples#

Set 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
}'

Mutate 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
}'

Mutate 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
}'

Segment Get

Description
Query parameters
Headers
Request body
Request parameters
Response parameters
Examples