List object versions

A version is a historical record of an object’s state. Listing versions returns the timestamps and version numbers needed to fetch a specific past state snapshot.

Retrieve the recorded state versions for a fully qualified object name. The root response is a JSON array, not a wrapper object; each row contains the server record timestamp rec, logical timestamp at, and numeric version.

Pass a returned version to Get object state to retrieve that snapshot. The number of retained historical states is controlled by the object's versionDeep setting, which you can inspect with Get an object.

A 404 means no object or state data exists under the supplied name. Confirm the name with List objects before retrying.

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

Query parameters#

  • objectstring
    Required

    Unique name of the object in the URL.

    format:
    abc:0-9@owner

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. **JSON array** (root is the array, not an object): one object per row with **`rec`**, **`at`**, and **`version`**.

    [

      {

        "rec": "2026-03-10T12:20:49.9206295+00:00",

        "at": "2023-04-24T20:15:10.0000000+00:00",

        "version": 1

      }

    ]
    • responsearray[object]

      Root JSON value is this array (not wrapped in an object).

      • response[0].recstring

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

      • response[0].atstring

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

      • response[0].versionnumber

        State version number (same notion as in `GET /v1/state`).

  • 401

    Unauthorized.

  • 403

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

  • 404

    No state or object data exists for the given name.

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

List object versions

JSON array of `{ rec, at, version }` rows for the object.

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

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

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

  --header 'Accept: application/json'
VersionToken

© 2024 BigState