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 26 characters of lowercase letters, digits, and hyphens, and unique within the workspace. The region and versioning live under the qibdo block, since they are specific to qibdo’s own engine:

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",
    "default_storage_class_id": "{storage_class_id}",
    "qibdo": {
      "region_id": "{region_id}",
      "versioning_enabled": true
    }
  }'

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.