State get

Read subject state for an object: the latest version, or a specific version via the version query parameter. The response includes owner, full object name, rec and at timestamps, version, type (encoding of the payload: 2 — JSON object, 3 — number, 4 — string, 5 — Base64 binary), optional ttl (seconds, when set on write), and value or valueRef. The value shape follows type.

GET
{{host}}/v1/state?object={{object name}}&version={{version}}
VERB:GET
BASE URL:{{host}}/v1/state
QUERY STRING:?object={{object name}}&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.

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

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. See the error codes reference for the full list.

    • descstring

      Human-readable description of the error.

Examples#

Get latest state

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 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'
SetMatch

© 2024 BigState