List stored values

A value is raw binary data stored separately from object state. Uploading a value returns an opaque valueRef that state can reference, so large or binary payloads stay out of the inline state body.

List stored values for a fully qualified object, optionally filtered by a glob-style pattern. Each result contains valueRef, fileName, fileMimeType, and fileSize in bytes; the response contains metadata, not the binary body.

Pagination requires next: start with next=0, then pass each returned cursor to the next request until the API returns -1. If a pattern returns no values, retry without it and confirm the fully qualified object name.

Pass a listed reference to Download a value to retrieve its bytes or Delete a value to remove it. New blobs are created with Upload a value.

GET

{{host}}/v1/value/match?object={{object}}&next={{next}}&pattern={{pattern}}

VERB:GET

BASE URL:{{host}}/v1/value/match

QUERY STRING:?object={{object}}&next={{next}}&pattern={{pattern}}

Query parameters#

RequiredOptional

objectstring
Required
Unique name of the object in the URL.
format:
abc:0-9@owner
nextnumber
Required
Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.
example: 0
patternstring
Optional
Optional glob-style pattern to filter.
Values
- pattern
- *pattern
- pattern*
- *pattern*
example: *

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.

Response parameters#

200Response body · object
Success. Pagination cursor and value metadata rows for this page (JSON body).
```
{
  "next": -1,
  "values": [
    {
      "valueRef": "u81kO8O3Pywb1yoxOZ2X6OJiwjihpEY42SQYRzbg",
      "fileName": "photo.png",
      "fileMimeType": "image/png",
      "fileSize": 7
    }
  ]
}
```
- nextnumber
  Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.
  example: 0
- valuesarray[object]
  Entries that matched the pattern on this page.
  - values[0].valueRefstring
    Blob identifier.
  - values[0].fileNamestring
    Stored file name.
  - values[0].fileMimeTypestring
    Stored MIME type.
  - values[0].fileSizenumber
    Size of the stored blob in bytes.
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
400Response body · object
Bad request.
```
{
  "error": 6,
  "desc": "Invalid request"
}
```
- errornumber
  Numeric error code. Use the response `desc` field for the human-readable explanation.
- descstring
  Human-readable description of the error.

Examples#

List stored values

List value metadata for an object; optional glob pattern on names (paginated with next).


curl 'https://api.bigstate.dev/v1/value/match?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%3Avalueref%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6&next=0&pattern=*photo*' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Download Delete

Description
Query parameters
Headers
Response parameters
Examples