List Objects
const url = 'https://example.com/storage/v1/workspaces/example/engines/example/buckets/example/objects';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/storage/v1/workspaces/example/engines/example/buckets/example/objectsLists one page of a bucket’s contents as a single ordered list of entries, each declaring itself a stored file or a directory. Supplying a delimiter (typically ”/”) groups everything below the next separator into a directory entry; supplying none returns every stored file exactly as stored, with nothing reported as a directory and nothing hidden.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The workspace the bucket belongs to
The cloud provider: qibdo, aws, gcp, or azure. ’-’ resolves to the platform’s default provider; it does NOT federate — this listing is served by exactly one provider, and a cross-provider listing is not offered.
The bucket to list objects from
Query Parameters
Section titled “Query Parameters ”Filter objects by key prefix. Retained as a dedicated field because key prefix matching is a fundamental server-side optimization that cannot be expressed in filter syntax without losing performance.
Delimiter for pseudo-directory listing (typically ”/”). Retained as a dedicated field because delimiter handling is a native server-side optimization not expressible via filter strings.
Maximum keys per page. The service may return fewer than this value. If unspecified, at most 20 objects will be returned. The maximum value is 100; values above 100 will be coerced to 100.
A page token, received from a previous ListObjects call.
Provide this to retrieve the subsequent page. When paginating,
all other parameters must match the call that provided the page token.
Responses
Section titled “ Responses ”OK
ListObjectsResponse
Response message for ListObjects.
Pass-through S3 listing — the backend provides no total count, so total_size is intentionally omitted (see ADR qib-522/0001).
object
The entries of this page, in one ordered list. It holds both stored files and directories; each entry declares which it is. No client-side merge, trim, filter or ordering step is required.
Ordering: entries are returned in ascending lexicographic order of the full name,
with files and directories interleaved in that single order. The order is over the
complete key — it is NOT two lists concatenated, so a directory may appear between two
files. Repeating an unchanged request returns the same order.
StorageObject
One entry in a directory listing: either a stored file or a directory.
object
The object’s full name — the complete key, slashes included, exactly as stored. THE IDENTIFIER: unique within a listing and sufficient for a follow-up request. A directory’s name ends in the delimiter.
A name’s slashes are sent percent-encoded (%2F) when it is used as a path segment; a literal ’:’ is sent %3A so the ‘:metadata’ custom verb stays unambiguous.
Free-text label relative to the request prefix, e.g. “2026” or “cover.jpg”. NOT unique within a listing — a file and a directory may share one. When no delimiter is supplied there is no grouping to strip, so this may contain delimiters. A presentation convenience, never an identifier.
Blob
A stored file. Population varies BY RPC: a provider’s list call returns an index, not the full record — absent means “not carried by this RPC on this provider”, never fabricated-empty.
object
The bucket that actually holds this file, as its platform identifier. Resolvable via GetBucket. Empty when the read path could not name the parent row.
Absent on a listing row; populated on Head/Get.
Change-detection token. Guaranteed only to change when the object changes.
NOT a content digest — providers compute it differently for multipart,
composite and encrypted objects, and one provider returns different values
for the same object across its own APIs. Use checksums for integrity.
Integrity digests, each carrying its own algorithm. May be empty: some objects genuinely have none. On a listing row emptiness is NOT proof of absence — see ListObjectsResponse.unpopulated_fields.
Checksum
One integrity digest.
object
An algorithm the platform catalogues.
The provider’s own algorithm token, verbatim, when the platform does not yet catalogue it. Read-side honesty only — a caller may never supply this arm.
Empty on a listing row; populated on Head/Get. Emptiness on a listing row is NOT proof of absence — see ListObjectsResponse.unpopulated_fields.
object
Absent on a listing row; populated on Head/Get.
Where a provider reports a single timestamp (the S3 family reports LastModified alone), create_time is ABSENT rather than a copy of update_time.
Directory
A directory. Empty on backends where directories are inferred from key names; gains fields when a backend can supply them honestly. Shipping always-absent fields would be dead surface, and a later addition is additive.
object
A token, which can be sent as page_token to retrieve the next page. An empty token —
and only an empty token — means the listing has ended. The server absorbs pages its own
filtering would leave empty, so an empty objects list with a non-empty token does not
occur; a page holding FEWER entries than page_size is normal and is not the end.
Never the provider’s raw continuation marker: it is wrapped and signed, binding the request parameters it was issued under, so a token replayed against a different workspace, bucket, prefix, delimiter or page size is refused rather than silently answering from the wrong listing.
Completeness is promised only for a folder that does not change while the walk is in progress: every entry is returned exactly once. If objects are written or deleted concurrently, an entry may be seen twice or not at all — a walk is not a point-in-time snapshot.
Blob field names this RPC did not populate for ANY row of this page — the honest-absence
marker for the fields proto3 gives no presence bit (metadata, checksum VALUES). A name
listed here carries no information for this page: read it with a per-object describe call.
Today this list is fixed for the listing RPC and is the same for every page and provider. It is not yet narrowed per provider, so a provider whose list call happens to return more than the guaranteed minimum is still reported conservatively; per-provider reporting is owed and will only ever shorten the list.
Example
{ "objects": [ { "blob": { "checksums": [ { "catalogued": "CHECKSUM_ALGORITHM_UNSPECIFIED" } ] } } ]}default
Section titled “default ”Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
object
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
A list of messages that carry the error details. There is a common set of message types for APIs to use.
Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
object
The type of the serialized message.
Example generated
{ "code": 1, "message": "example", "details": [ { "@type": "example" } ]}