> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/platform-api/list-workspaces/create-bucket.md).

# Create Bucket

Create a bucket inside a Nebula Block object storage workspace.

Create a bucket inside a workspace.

## HTTP Request

`POST` `{API_URL}/object-storage/bucket`

where `API_URL = https://api.nebulablock.com/api/v1`.

## Body Parameters

| Parameter             | Requirement | Type      | Description                                                                                                                           |
| --------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `bucket_name`         | Required    | `string`  | The name of the bucket                                                                                                                |
| `object_storage_name` | Required    | `string`  | The workspace to create it in                                                                                                         |
| `region`              | Optional    | `string`  | The region to create the bucket in — `ca-central`. Safe to omit: the console does not send it and bucket creation succeeds without it |
| `team_id`             | Optional    | `integer` | Create under a team's storage. See [Teams](/account/teams.md)                                                                         |

> **Important:** The bucket is not created under the name you supply. The platform prefixes it, so `docs-verify` inside workspace `Personal0616-1` becomes `u-2f36933d-personal0616-1.docs-verify`. Read the resulting name from [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md) — that `id` is what `s3cmd` and the S3 API see. Buckets created before the storage backend was migrated keep their original unprefixed names.

New buckets are **private** by default. See [Toggle Bucket Privacy](/api-reference/platform-api/list-workspaces/toggle-bucket-privacy.md).

## Response Attributes

#### data `dict`

The created bucket:

* **bucket\_name** `string`: The bucket's name.
* **region** `string`: The region it was created in.
* **domain** `string`: The domain the bucket is served from.
* **status** `string`: `success`.

On failure `data` is `null` and `message` carries the provider's error.

> **Note:** Business failures on this endpoint are returned as **HTTP 200 with `"status": "failed"`** and an explanatory `message`. Check `status`, not just the HTTP status code.

## Example

#### Request

```bash
curl -X POST '{API_URL}/object-storage/bucket' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"object_storage_name": "research-datasets", "bucket_name": "checkpoints"}'
```

#### Response

```json
{
    "data": {
        "status": "success",
        "bucket_name": "checkpoints",
        "region": "ca-central",
        "domain": "..."
    },
    "message": "Bucket 'checkpoints' was created successfully.",
    "status": "success"
}
```

## See also

* [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md)
* [Delete Bucket](/api-reference/platform-api/list-workspaces/delete-bucket.md)
* [Upload File](/api-reference/platform-api/list-workspaces/upload-file.md)