List object segments

An object is a named resource whose definition describes the state it accepts. An object can represent a device, user location, counter, or any other stateful entity, including type, retention, and version-history settings.

List immediate child segment names under an optional path. Results are short, one-level labels rather than fully qualified object names; omit path to start at the root visible to the current API key.

The next cursor is required: use 0 for the first page and continue with the returned cursor until the API returns -1. The optional glob-style pattern filters the segments in the selected path.

Use List objects when you need full object names. If a segment is missing, retry without pattern and confirm that path identifies its immediate parent.

GET
{{host}}/v1/object/segment?path={{path}}&next={{next}}&pattern={{pattern}}
VERB:GET
BASE URL:{{host}}/v1/object/segment
QUERY STRING:?path={{path}}&next={{next}}&pattern={{pattern}}

Query parameters#

  • pathstring
    Optional

    Parent path whose immediate child segments are listed. Omit to start from the root of the namespace your key can see.

    example: {{owner}}:position
  • 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#

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 a pagination cursor and the immediate child segment names for this page (not full object names).

    • 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
    • segmentsarray[string]

      Short segment labels one level below the requested path (e.g. a single path component each), not full name@owner strings.

  • 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. Use the response `desc` field for the human-readable explanation.

    • descstring

      Human-readable description of the error.

Examples#

List object segments

List objects under a path prefix with a wildcard pattern (paginated).

curl 'https://api.bigstate.dev/v1/object/segment?path=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition&next=0&pattern=*' \

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

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

  --header 'Accept: application/json'
ListState

© 2024 BigState