--- name: azion-create-a-bucket description: >- Create an Object Storage bucket from Azion Console, the Azion API, or the Azion CLI, then list, update, and delete your buckets. --- # Create a bucket You create a bucket in [Object Storage](/en/documentation/platform/object-storage/) from Azion Console, the Azion API, or the Azion CLI. The same three interfaces list your buckets, change a bucket's access level, and delete a bucket. A new bucket carries the name and the access level you set, and it appears in the bucket list of your account. For the objects that go inside it, refer to [Upload and download objects](/en/documentation/guides/application-development/data/upload-and-download-objects-from-bucket/). --- ## Prerequisites - A bucket name of 6 to 63 characters, built from letters, numbers, and the hyphen. The name cannot begin with `azion`, and it is unique across every Azion account. A name that states the purpose, such as `media-assets-prod`, keeps a long list readable. - Access to Azion Console, for the Console procedure. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/), for the API procedures. - The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized, for the CLI procedures. --- ## Create a bucket using Azion Console The create form asks for two values, one in **General** and one in **Settings**. To create the bucket: 1. **Open the bucket list** Access [Azion Console](https://console.azion.com/) > **Object Storage**, and start a new bucket from the **Buckets** list. 2. **Name the bucket** In **General**, enter a **Name** that identifies what the bucket holds. 3. **Set the access level** In **Settings**, set **Workloads Access** to the level the platform needs. The field defaults to *Read Only*: - *Read Only*: the platform reads objects and does not modify them. Use it to serve static content through an application. - *Read & Write*: the platform reads and writes objects, so a function can store data in the bucket. - *Restricted*: the platform neither reads nor writes, and the bucket cannot back an application. The API and the S3 protocol still reach it. 4. **Select Create Bucket** The bucket appears in the **Buckets** list with the name you set. --- ## Create a bucket using the API Send a `POST` request to the buckets endpoint. Both `name` and `workloads_access` are required, and the create schema stores no other field. To create the bucket: 1. **Send the create request** ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/storage/buckets' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"name":"my-bucket-ro","workloads_access":"read_only"}' ``` 2. **Read the response** The API answers with HTTP `201`, or `202` when it processes the request asynchronously, and returns the bucket it stored: ```json { "state": "executed", "data": { "name": "my-bucket-ro", "workloads_access": "read_only", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.000000+00:00", "product_version": "1.0" } } ``` The bucket is stored under the name in `data.name`, and `last_editor`, `last_modified`, and `product_version` are read-only. --- ## Create a bucket using the Azion CLI The noun is `storage`, and the access level travels in `--workloads-access`. To create the bucket: ```bash azion create storage bucket --name my-bucket-ro --workloads-access read_only ``` The command prints one line: ```text Bucket created successfully ``` Run the command without flags and the Azion CLI prompts for each value. `azion create storage bucket -h` lists every flag it accepts. --- ## List your buckets Every interface returns the buckets of the account you are authenticated as. ### Azion Console The [Object Storage page](https://console.azion.com/object-storage) of Azion Console lists every bucket created in your account, under the **Object Storage** > **Buckets** breadcrumb. Each row carries **Name**, **Size**, **Last Editor**, and **Last Modified**. ### The API Send a `GET` request to the buckets endpoint: ```bash curl --location 'https://api.azion.com/v4/workspace/storage/buckets' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The response carries the buckets under `results`, with the page it belongs to: ```json { "count": 1, "total_pages": 1, "page": 1, "page_size": 100, "results": [ { "name": "my-bucket-ro", "workloads_access": "read_only", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.000000+00:00", "product_version": "1.0" } ] } ``` The envelope also carries `next` and `previous`. Page through a longer list with `page` and `page_size`, where `page_size` stops at 100. To find one bucket, `search` matches a name partially and `name` matches it exactly. ### The Azion CLI Send the list command, with the page size you want: ```bash azion list storage bucket --page-size 10 ``` The command prints a table with a `NAME` column and a `WORKLOADS ACCESS` column, and `--page` moves to the next page. --- ## Change a bucket's access level `workloads_access` decides what the Azion platform may do with the bucket. It does not restrict the API or the S3 protocol: a credential that carries `writeFiles` writes to a `read_only` bucket. | Value | Console label | The Azion platform may | The API and the S3 protocol may | | ------------ | -------------- | ----------------------------------------------------------------- | ---------------------------------- | | `read_only` | *Read Only* | Read objects | Read and write, per the credential | | `read_write` | *Read & Write* | Read and write objects | Read and write, per the credential | | `restricted` | *Restricted* | Neither read nor write, and the bucket cannot back an application | Read and write, per the credential | > **Caution** > > A bucket set to `read_write` and served by an application can be modified by anyone who reaches it, by a `PUT` request that overwrites an object. A function in front of the bucket moves that decision into code you control, so the function grants or refuses each write. Set the level each use case needs, and pair it with the account permissions described in [Teams and permissions](/en/documentation/fundamentals/teams-permissions/). ### Azion Console To change the level: 1. **Open the bucket** Access [Azion Console](https://console.azion.com/) > **Object Storage**, then select the bucket in the **Buckets** list. The **Bucket settings** page opens. 2. **Set the new level** In **Settings**, set **Workloads Access** to the value you want. 3. **Select Save** The bucket carries the new access level. ### The API Send a `PATCH` request to the bucket, with `workloads_access` as the only field: ```bash curl --location --request PATCH 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket-ro' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"workloads_access":"read_write"}' ``` The API answers with HTTP `200`, or `202` when it processes the request asynchronously, and returns the bucket with the new level: ```json { "state": "executed", "data": { "name": "my-bucket-ro", "workloads_access": "read_write", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.000000+00:00", "product_version": "1.0" } } ``` > **Note** > > A bucket cannot be renamed. A `name` field in a `PATCH` body returns HTTP `400` with error `17004`, `Name Cannot Be Changed`. To use a different name, create a second bucket and move the objects into it. ### The Azion CLI Name the bucket with `--name` and the new level with `--workloads-access`: ```bash azion update storage bucket --name my-bucket-ro --workloads-access read_write ``` The command prints one line: ```text Bucket updated successfully ``` `azion update storage bucket -h` lists every flag it accepts. --- ## Delete a bucket A bucket is deleted only while it is empty. > **Caution** > > Azion refuses to delete a bucket that holds objects, and refuses for 24 hours after its last object was removed, because a deleted object is permanently removed after a 24-hour grace period. Either request returns HTTP `400` with error `17006`, `Cannot Delete Non Empty Bucket`. A bucket that never held an object is deleted at once. ### Azion Console To delete the bucket: 1. **Open the bucket** Access [Azion Console](https://console.azion.com/) > **Object Storage**, then select the bucket in the **Buckets** list. The **Bucket settings** page opens. 2. **Select Delete Bucket** The control sits in **Danger Zone**, which warns that the action permanently removes the bucket and all of its associated data from the Azion platform, and cannot be undone. The bucket leaves the **Buckets** list. ### The API Send a `DELETE` request to the bucket: ```bash curl --location --request DELETE 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket-ro' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The API answers with `state` set to `executed`: ```json {"state": "executed"} ``` ### The Azion CLI Name the bucket with `--name`: ```bash azion delete storage bucket --name my-bucket-ro ``` The command names the bucket it removed: ```text Bucket my-bucket-ro was deleted successfully ``` A deleted bucket no longer answers any request, and the API returns error `17005`, `Bucket Does Not Exist`, for it. --- ## Next steps - [Upload and download objects](/en/documentation/guides/application-development/data/upload-and-download-objects-from-bucket.md): Put objects in the bucket you created, read them back, and remove them. - [Use a bucket as an application origin](/en/documentation/guides/application-development/data/use-bucket-as-origin.md): Serve the objects to the public through a connector and a Rules Engine rule. - [Buckets and objects](/en/documentation/platform/object-storage/buckets-and-objects.md): Every field, operation, and default of the bucket and object endpoints. - [Use S3-compatible tools](/en/documentation/guides/application-development/data/use-s3-compatible-tools-with-object-storage.md): Reach the bucket with an S3 credential from the tools you already run.