Skip to navigation

A bucket is a named container for your files (objects) in IBEE Object Storage. Every object lives in exactly one bucket. A bucket belongs to one workspace, sits in one location, and is private until you choose otherwise. Settings such as public access, CORS and lifecycle rules apply to the whole bucket.

When to use one bucket or several

SituationRecommendation
One app, one environmentOne bucket, with prefixes (uploads/, thumbnails/) for “folders”
Production and stagingSeparate buckets, so a staging credential can’t touch production
Public website files and private user dataSeparate buckets: Public Access opens a whole bucket
Records that must not be changed for yearsA separate bucket created with Object lock (WORM)
Data in another locationA bucket in that location (the location can’t be changed later)

How it works

  1. You create a bucket with a name, a location and a storage type. Creation usually takes a few seconds.
  2. You use it from the portal or any S3 tool, and change its settings on the Settings tab.
  3. To remove it, you empty it, then delete it.

Before you begin

  • Identity verification completed. Until then the portal shows Verify Identity in place of Create Bucket. See Verify your identity.
  • For organizations billed in India: a verified payment method. Until then the portal shows Verify payment method in place of Create Bucket. See Verify a payment method.
  • Wallet credit or billing set up. See Pricing.
  • Permission to create resources in the workspace.

Naming rules

Bucket names must:

  • be 3 to 63 characters long;
  • use only lowercase letters, numbers and hyphens (-) — no dots, underscores, spaces or capitals;
  • start and end with a letter or number;
  • be unique within the workspace (other workspaces can use the same name).
NameValid?
my-bucket, data-store-01Yes
My-BucketNo — uppercase
-assets, assets-No — starts or ends with a hyphen
project_assets, project.assetsNo — underscore or dot
abNo — fewer than 3 characters

Create a bucket

1

Open Object Storage

In the portal sidebar, click Object Storage under Infrastructure, then Create Bucket.

2

Enter the bucket name

Under Bucket name, type the name (placeholder my-unique-bucket-name). The hint below reads 3-63 characters, lowercase letters, numbers, and hyphens only.

3

Choose the location

The Location section has two tabs:

  • Automatic: keep Automatic location to let IBEE pick an available location, or click Need a specific location? click here and pick a site. Available sites show their country; pre-order sites show Talk to Sales.
  • Specify jurisdiction: This feature is coming soon. For jurisdiction-based placement, talk to sales.

Choosing a pre-order site or the jurisdiction tab changes the footer button to Talk to Sales.

4

Choose the storage type

Under Storage type, pick one of the plans offered for the location.

5

Decide on versioning and Object Lock

Under Versioning and object lock:

SwitchEffect
VersioningKeeps old versions of overwritten or deleted objects. On its own it isn’t applied yet: versioning is turned on only with Object lock (WORM).
Object lock (WORM)Protects objects from deletion or overwriting for a retention period. Also turns on Versioning. Permanent: it can only be set now, and a bucket with it can never be deleted.

With Object lock (WORM) on, choose a default retention mode — None, Governance or Compliance — and for Governance or Compliance a Retention period in days (default 30, at least 1). See Object Locking.

6

Create the bucket

Click Create Bucket. The page shows Creating bucket…, then Bucket created successfully. After 10 seconds it says This is taking longer than usual. We’re still creating your bucket.; click Check status to check again.

Create a bucket with the API

Use a platform API token with the object-storage.write scope. region is required and must be the Object Storage region identifier for your environment — not a compute site ID or a display name. If you don’t know it, ask support before creating the bucket.

curl -X POST "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=YOUR-WORKSPACE-ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "production-assets", "region": "YOUR-OBJECT-STORAGE-REGION", "is_public": false}'

Add "object_lock_enabled": true and "default_retention": {"mode": "GOVERNANCE", "days": 30} to create it with Object Lock. Don’t send site_id.

Verify

The bucket appears in the list on the Object Storage page with its BUCKET name, SIZE and CREATED date. Once you have buckets, the panel at the top shows Buckets, Objects, Storage Used and Bandwidth Egress for the current billing month. Use Search buckets… to filter.

The bucket page

Click a bucket to open it. It has three tabs:

TabUse
ObjectsUpload, download, create folders and delete files. See Objects.
MetricsStorage and request figures. See Metrics.
SettingsBucket configuration, in the tabs below
Settings tabWhat it controls
GeneralName, creation date, Total Objects, Storage Used, the Public Access switch and Public Access URL, the Object Lock state (read-only), and the Danger Zone (Empty bucket, Delete bucket)
Lifecycle PoliciesAutomatic deletion of old objects. See Lifecycle Management.
CORSWhich websites may use the bucket from a browser. See CORS.
Lock SettingsObject Lock default retention (buckets created with Object Lock). See Object Locking.
Event NotificationsWebhooks when objects are uploaded. See Event Notifications.
Custom DomainsServe a public bucket from your own hostname. See Custom Domains.

Empty a bucket

Empty bucket permanently deletes every object in a bucket and keeps the bucket and its settings. It runs in the background.

Emptying a bucket can’t be undone. Download anything you need first. Empty bucket isn’t available for buckets with Object Lock or Versioning; delete objects in those with an S3 tool.

1

Open the Danger Zone

Open the bucket → Settings → General. The Danger Zone card is at the bottom.

2

Start the job

Click Empty bucket. The dialog says how many objects will be permanently deleted. Type the bucket name and click Empty bucket.

3

Follow the progress

A status strip shows Emptying bucket… with the count of objects deleted, then Finalizing empty bucket…. Click Cancel to stop it; objects already deleted stay deleted. When it ends you see Bucket contents were deleted, Bucket partially emptied, Some objects are protected, Couldn’t empty bucket or Empty bucket cancelled.

Delete a bucket

Only empty buckets can be deleted. A bucket with objects shows This bucket contains X objects. Empty it first to delete.

  1. Empty the bucket (above).
  2. On Settings → General, click Delete bucket in the Danger Zone, or the delete icon in the bucket list.
  3. Confirm with Delete. The toast Bucket ‘NAME’ deleted successfully appears. This can’t be undone.

A bucket created with Object lock (WORM) can’t be deleted, even when empty: Bucket cannot be deleted because Object Lock is enabled.

Use the API

All bucket operations use https://api.ibee.ai/v1/object-storage with workspace_id and a platform API token:

TaskOperationScope
List, createGET, POST /bucketsobject-storage.read, object-storage.write
Get, change public access, deleteGET, PATCH (is_public), DELETE /buckets/{bucket_name}read, write, object-storage.delete
Lifecycle, CORS, notificationsGET, PUT, DELETE /buckets/{bucket_name}/lifecycle, …/cors, …/notificationsread, write, object-storage.delete
Object Lock default retentionGET, PUT /buckets/{bucket_name}/object-lockread, write
Custom domainsGET, POST /buckets/{bucket_name}/custom-domains; DELETE …/custom-domains/{domain}read, write, object-storage.delete
MetricsGET /buckets/{bucket_name}/metrics?range=24h (or 7d)read

Objects, folders and per-object retention use the S3 API. Empty bucket and the Public Access URL have no API operation; use the portal.

Limits

Value
Name3–63 characters, unique in the workspace
LocationFixed at creation
Default accessPrivate
Bucket creationUsually a few seconds; the portal warns after 10 seconds
Object Lock default retention at creation30 days by default, at least 1 day
DeletingBucket must be empty; never possible with Object Lock

Troubleshooting

You seeWhat it meansWhat to do
Bucket name must be at least 3 charactersThe name is too shortUse 3–63 characters.
Bucket name must start and end with a letter or number, and contain only lowercase letters, numbers, and hyphensInvalid charactersUse lowercase letters, numbers and hyphens.
Bucket already existsThe workspace already has a bucket with that namePick another name.
Talk to Sales instead of Create BucketYou chose a pre-order site or Specify jurisdictionChoose Automatic location or an available site.
Creation status is unconfirmed. Check status before trying again.The portal lost track of the requestClick Check status before creating it again.
Delete bucket is disabledThe bucket still has objectsEmpty it first.
Bucket cannot be deleted because Object Lock is enabled.Object Lock buckets are permanentStop using the bucket; it can’t be deleted.
Empty bucket isn’t offeredThe bucket has Object Lock or VersioningDelete objects with an S3 tool, for example aws s3 rm s3://BUCKET --recursive.