> For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://ibee.ai/docs/llms.txt (full text of every page: https://ibee.ai/docs/llms-full.txt). For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ibee.ai/docs/_mcp/server. # Buckets > Create, configure, empty and delete IBEE Object Storage buckets — name rules, location, versioning and Object Lock choices, the settings tabs, and the REST API. 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 | Situation | Recommendation | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | One app, one environment | One bucket, with prefixes (`uploads/`, `thumbnails/`) for "folders" | | Production and staging | Separate buckets, so a staging credential can't touch production | | Public website files and private user data | Separate buckets: [Public Access](/docs/infrastructure/object-storage/buckets/bucket-policies) opens a whole bucket | | Records that must not be changed for years | A separate bucket created with **Object lock (WORM)** | | Data in another location | A 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](/docs/getting-started/account-setup/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](/docs/infrastructure/object-storage/payment-verification). * Wallet credit or billing set up. See [Pricing](/docs/infrastructure/object-storage/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). | Name | Valid? | | ---------------------------------- | --------------------------------- | | `my-bucket`, `data-store-01` | Yes | | `My-Bucket` | No — uppercase | | `-assets`, `assets-` | No — starts or ends with a hyphen | | `project_assets`, `project.assets` | No — underscore or dot | | `ab` | No — fewer than 3 characters | ## Create a bucket ### Open Object Storage In the portal sidebar, click **Object Storage** under **Infrastructure**, then **Create Bucket**. ### 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.* ### 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**. ### Choose the storage type Under **Storage type**, pick one of the plans offered for the location. ### Decide on versioning and Object Lock Under **Versioning and object lock**: | Switch | Effect | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Versioning** | Keeps 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](/docs/infrastructure/object-storage/objects/object-locking). ### 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 > **Warning** > > **Temporarily paused:** managing Object Storage and Container Registry through the API, SDKs, CLI and Terraform. Until it resumes, these calls answer `404` with an empty body. That doesn't mean your resource was deleted. The portal, S3 file traffic, registry pushes and pulls, and your existing resources keep working. The API, CLI and Terraform steps for these products apply once it resumes. If you use Terraform, [read this first](/docs/api-reference/terraform#paused-object-storage-and-container-registry). Use a [platform API token](/docs/tools/api-tokens) 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. ```bash 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: | Tab | Use | | ------------ | -------------------------------------------------------------------------------------------------------------- | | **Objects** | Upload, download, create folders and delete files. See [Objects](/docs/infrastructure/object-storage/objects). | | **Metrics** | Storage and request figures. See [Metrics](/docs/infrastructure/object-storage/metrics). | | **Settings** | Bucket configuration, in the tabs below | | Settings tab | What it controls | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **General** | Name, 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 Policies** | Automatic deletion of old objects. See [Lifecycle Management](/docs/infrastructure/object-storage/buckets/lifecycle-management). | | **CORS** | Which websites may use the bucket from a browser. See [CORS](/docs/infrastructure/object-storage/buckets/cors). | | **Lock Settings** | Object Lock default retention (buckets created with Object Lock). See [Object Locking](/docs/infrastructure/object-storage/objects/object-locking). | | **Event Notifications** | Webhooks when objects are uploaded. See [Event Notifications](/docs/infrastructure/object-storage/buckets/event-notifications). | | **Custom Domains** | Serve a public bucket from your own hostname. See [Custom Domains](/docs/infrastructure/object-storage/buckets/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. > **Warning** > > 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. ### Open the Danger Zone Open the bucket → **Settings** → **General**. The **Danger Zone** card is at the bottom. ### Start the job Click **Empty bucket**. The dialog says how many objects will be permanently deleted. Type the bucket name and click **Empty bucket**. ### 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. > **Note** > > 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 > **Warning** > > **Temporarily paused:** managing Object Storage and Container Registry through the API, SDKs, CLI and Terraform. Until it resumes, these calls answer `404` with an empty body. That doesn't mean your resource was deleted. The portal, S3 file traffic, registry pushes and pulls, and your existing resources keep working. The API, CLI and Terraform steps for these products apply once it resumes. If you use Terraform, [read this first](/docs/api-reference/terraform#paused-object-storage-and-container-registry). All bucket operations use `https://api.ibee.ai/v1/object-storage` with `workspace_id` and a platform API token: | Task | Operation | Scope | | --------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------- | | List, create | `GET`, `POST /buckets` | `object-storage.read`, `object-storage.write` | | Get, change public access, delete | `GET`, `PATCH` (`is_public`), `DELETE /buckets/{bucket_name}` | read, write, `object-storage.delete` | | Lifecycle, CORS, notifications | `GET`, `PUT`, `DELETE /buckets/{bucket_name}/lifecycle`, `…/cors`, `…/notifications` | read, write, `object-storage.delete` | | Object Lock default retention | `GET`, `PUT /buckets/{bucket_name}/object-lock` | read, write | | Custom domains | `GET`, `POST /buckets/{bucket_name}/custom-domains`; `DELETE …/custom-domains/{domain}` | read, write, `object-storage.delete` | | Metrics | `GET /buckets/{bucket_name}/metrics?range=24h` (or `7d`) | read | Objects, folders and per-object retention use the [S3 API](/docs/infrastructure/object-storage/s3-api). **Empty bucket** and the Public Access URL have no API operation; use the portal. ## Limits | | Value | | ----------------------------------------- | -------------------------------------------------------- | | Name | 3–63 characters, unique in the workspace | | Location | Fixed at creation | | Default access | Private | | Bucket creation | Usually a few seconds; the portal warns after 10 seconds | | Object Lock default retention at creation | 30 days by default, at least 1 day | | Deleting | Bucket must be empty; never possible with Object Lock | ## Troubleshooting | You see | What it means | What to do | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------- | | *Bucket name must be at least 3 characters* | The name is too short | Use 3–63 characters. | | *Bucket name must start and end with a letter or number, and contain only lowercase letters, numbers, and hyphens* | Invalid characters | Use lowercase letters, numbers and hyphens. | | *Bucket already exists* | The workspace already has a bucket with that name | Pick another name. | | **Talk to Sales** instead of **Create Bucket** | You chose a pre-order site or **Specify jurisdiction** | Choose **Automatic location** or an available site. | | *Creation status is unconfirmed. Check status before trying again.* | The portal lost track of the request | Click **Check status** before creating it again. | | **Delete bucket** is disabled | The bucket still has objects | Empty it first. | | *Bucket cannot be deleted because Object Lock is enabled.* | Object Lock buckets are permanent | Stop using the bucket; it can't be deleted. | | **Empty bucket** isn't offered | The bucket has Object Lock or Versioning | Delete objects with an S3 tool, for example `aws s3 rm s3://BUCKET --recursive`. | ## Related pages * [Bucket Policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [Objects](/docs/infrastructure/object-storage/objects) * [Core Concepts](/docs/infrastructure/object-storage/core-concepts) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Limits](/docs/infrastructure/object-storage/limits) ## Docs - [Bucket Policies](https://ibee.ai/docs/infrastructure/object-storage/buckets/bucket-policies.md): Control bucket access in IBEE Object Storage — toggle public access, scope API credential permissions to specific buckets, and use bucket-level access controls. - [Lifecycle Management](https://ibee.ai/docs/infrastructure/object-storage/buckets/lifecycle-management.md): Lifecycle rules delete old objects in an IBEE Object Storage bucket automatically — after a number of days or on a date, for the whole bucket or one prefix. Portal steps, API, limits and fixes. - [CORS](https://ibee.ai/docs/infrastructure/object-storage/buckets/cors.md): CORS rules let web pages on your domain read from or upload to an IBEE Object Storage bucket from the browser. When you need them, how to add a rule, origin formats, the 5-minute cache, and how to fix CORS errors. - [Custom Domains](https://ibee.ai/docs/infrastructure/object-storage/buckets/custom-domains.md): Serve a public IBEE Object Storage bucket from your own hostname, such as assets.example.com, with automatic HTTPS. DNS record, portal steps, statuses, API, billing and fixes. - [Event Notifications](https://ibee.ai/docs/infrastructure/object-storage/buckets/event-notifications.md): Event notifications send an HTTP POST to your webhook when a file is uploaded to an IBEE Object Storage bucket. When to use them, portal steps, prefix and suffix filters, the API, limits and fixes.