Create a bucket

This guide walks through creating a bucket, choosing its region and default storage class, and confirming the result.

Before you begin

• Authentication. Export an API token as $QIBDO_API_TOKEN and the API base URL as $QIBDO_API_BASE. See Authenticate a user and manage the session.
• Permissions. Your identity needs permission to manage storage resources in the target workspace. See the authorization model.
• Prerequisites. A workspace and a target region that has a storage class.

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

1. Choose a region and storage class

List the storage classes available in your target region and pick one for the bucket default:

curl -sS \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_BASE/storage/v1/regions/{region}/engines/qibdo/storage-classes"

Note the id of the storage class you want as the default (for example, one named STANDARD) and the region it belongs to. Use a storage class from the same region as the bucket.

2. Create the bucket

Create the bucket with a POST. The name must be 3 to 63 characters, made of lowercase dot-separated labels using letters, digits and hyphens, with hyphens only inside a label and never as an IPv4 address. It is unique within the workspace.

The location and the default_storage_class are references to other resources. A reference takes either the resource’s id or its name, and you set exactly one of the two — supplying both is rejected:

curl -sS -X POST \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$QIBDO_API_BASE/storage/v1/workspaces/{workspace}/engines/qibdo/buckets" \
  -d '{
    "name": "app-assets",
    "description": "Public assets for the web app",
    "location": { "name": "eu-west-1" },
    "default_storage_class": { "name": "standard" },
    "versioning": "BUCKET_VERSIONING_ENABLED"
  }'

Referring by name is usually what you want in a script, because a name is readable and stable in your own configuration. Referring by id is exact, and is what you already have if you fetched the resource earlier in the same flow.

When the bucket is read back, both halves are returned for every reference — the id and the name together — so a caller that displays a reference and a caller that joins on one are each satisfied by a single response.

The call completes synchronously. It returns an operation record that is already marked done, with the new bucket’s id in its resource_id.

3. Verify the bucket

Fetch the bucket back with a GET, using the resource_id from the operation:

curl -sS \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_BASE/storage/v1/workspaces/{workspace}/engines/qibdo/buckets/{id}"

You can also list the buckets in the workspace, narrowing and ordering the results with the filter and order_by query parameters:

curl -sS \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  "$QIBDO_API_BASE/storage/v1/workspaces/{workspace}/engines/qibdo/buckets?order_by=name%20asc&page_size=20"

Notes

• The operation comes back already done. You can re-read it later at the operations endpoint, $QIBDO_API_BASE/storage/v1/operations/{id}.
• To change the description, versioning, or default storage class later, send a PATCH to the bucket with an update mask naming the fields to change.
• A bucket can be deleted only when it is empty. Deleting a bucket that still holds objects fails and leaves it in place, so remove its objects first.

Next

• Review the buckets and objects concept page.
• Learn how region-scoped storage classes define the tiers a bucket can default to.