Buckets and objects

Storage uses a simple two-level model: workspace-scoped buckets that hold objects. This page explains what each one is and how it behaves. It stays conceptual; the API reference is where the exact fields, methods, and limits live.

Buckets

A bucket is a container for objects. Every bucket belongs to one workspace and is provisioned on a cloud provider. It has a human-readable name that is unique within its workspace, an optional description, and a default storage class, a reference to one of the storage classes available to it.

On qibdo’s own engine, a bucket lives in a single region, chosen when you create it and fixed afterward, and supports versioning. With versioning on, the service keeps prior copies of an object instead of discarding them when it changes, so you can recover an earlier one. See Object versioning below.

A bucket must be empty before it can be deleted. The service refuses to delete a bucket that still holds objects, so remove its objects first.

Objects

An object is a single piece of stored data, for example an image, an archive, or a backup, together with the metadata that describes it. Each object is identified by a key within its bucket, a path-like string such as images/2026/logo.png. The key looks like a file path, but objects live in a flat namespace: the slashes are part of the name, not real folders. You can still list objects by a shared prefix to browse them as if they were directories.

Along with its bytes, every object carries metadata you can read without downloading the body:

its size,
a content type, the MIME type such as image/png,
a checksum that fingerprints the stored content,
the last-modified time,
an optional set of user metadata key-value pairs you attach yourself,
the storage class the object is stored in,
and, when the bucket has versioning on, a version identifier.

Listing objects

Object listings are narrowed with prefix and delimiter, not with the platform’s filter parameter. prefix restricts results to keys that begin with a string, and delimiter collapses everything after its next occurrence into a shared prefix, which is how a flat namespace is browsed as though it had folders:

curl --get https://api.qibdo.example.com/storage/v1/workspaces/$WORKSPACE/engines/qibdo/buckets/$BUCKET/objects \
  --header "Authorization: Bearer $QIBDO_API_TOKEN" \
  --data-urlencode "prefix=images/2026/" \
  --data-urlencode "delimiter=/"

This listing accepts no filter, and that is a property of object storage rather than a gap in the API. A bucket is a flat keyspace, not a table. There are no indexed columns for a predicate to be evaluated against, so answering a query like “objects larger than 10 MB” would mean reading the metadata of every object in the bucket and discarding most of it. On a bucket holding millions of keys that is not a filter, it is a full scan billed to the caller.

What the keyspace is built for is ordered traversal by key, which is exactly what prefix and delimiter express. Narrow by prefix first, then apply any further conditions on the page you get back. Listing multipart uploads follows the same reasoning and takes prefix only.

Every other qibdo Cloud listing uses the AIP-160 filter language described in Filtering.

Object versioning

Versioning is a per-bucket setting. While it is off, writing to an existing key replaces the object in place. While it is on, each write preserves the previous content as a distinct version, and every version is addressable by its own version identifier, so you can recover or roll back to an earlier copy. Turning versioning off again stops new versions from being created but leaves existing ones intact.

Object integrity

Every object carries a checksum derived from its content. Because identical content always yields the same checksum, you can compare the value the service reports against one you compute locally to confirm an upload or download arrived intact. Objects assembled from several parts use a checksum computed from those parts, so treat it as an identifier for that specific assembly rather than a plain digest of the whole.

Storage classes: how a bucket’s default storage class selects the tier objects are stored in.
Create a bucket.