Get 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.

Read the latest state of an object, or request a specific version with the version query parameter. The response includes the owner, fully qualified object name, rec and at timestamps, version, payload type, optional ttl, and either value or valueRef.

Payload types are 2 — JSON object, 3 — number, 4 — string, and 5 — Base64 binary string. The shape of value follows the configured type.

A 404 means no state exists for the supplied object or version. Use List object versions to find available versions, Set object state to write a new state, or Download a value to resolve a returned valueRef.

GET
{{host}}/v1/state?object={{object}}&version={{version}}
VERB:GET
BASE URL:{{host}}/v1/state
QUERY STRING:?object={{object}}&version={{version}}

Query parameters#

  • objectstring
    Required

    Unique name of the object in the URL.

    format:
    abc:0-9@owner
  • versionnumber
    Optional

    Return this version of the state. Omit to get the latest version.

    example: 1

Headers#

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.

Response parameters#

  • 200Response body · object

    Success. Returns owner, object name, record and logical timestamps, version, state `type`, optional `ttl`, and either `value` or `valueRef` depending on how the object stores state.

    {

      "owner": "Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6",

      "object": "Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6:position@Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6",

      "rec": "2026-03-31T13:54:39.1271586+00:00",

      "at": "2026-03-31T13:54:39.1271587+00:00",

      "version": 43,

      "type": 2,

      "ttl": 600,

      "value": {

        "lat": 32,

        "lng": 12

      }

    }
    • ownerstring

      Owner identifier for this object.

    • objectstring

      Fully qualified object name (name@owner).

    • recstring

      Server record timestamp for this state row (ISO 8601 with offset).

    • atstring

      Logical timestamp of the state value (ISO 8601 with offset).

    • versionnumber

      Version number of this state snapshot.

    • typenumber

      How the state payload is encoded — same numbering as the object definition `type` and POST /v1/state `value`.

      Values

      • 2 — JSON object
      • 3 — number
      • 4 — string
      • 5 — Base64 binary data
      example: 2
    • ttlnumber

      Optional. Time-to-live for this state row in seconds, when one was set on write.

      example: 600
    • valueany

      Inline state payload; shape follows the object’s value type (see object definition `type`).

      Values

      • 2 — JSON object
      • 3 — number
      • 4 — string
      • 5 — Base64 binary data
    • valueRefstring

      Reference to externally stored payload when the object uses reference-backed state.

  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 404

    No state exists for the given object (or version).

  • 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#

Get object state (latest)

Read the most recent state for an object.

curl 'https://api.bigstate.dev/v1/state?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json'

Get object state by version

Read a specific version of state.

curl 'https://api.bigstate.dev/v1/state?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6&version=1' \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json'
Set stateList states

© 2024 BigState