> 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/toggle-bucket-privacy.md).

# Toggle Bucket Privacy

Flip a bucket between public and private, which determines whether download URLs are signed.

Flip a bucket between public and private. This is a toggle, not a setter — it switches the bucket to whichever state it is not currently in, so read the current value from [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md) first if you need a specific outcome.

Bucket privacy determines what [Get Download URL](/api-reference/platform-api/list-workspaces/get-download-url.md) hands back: private buckets produce expiring pre-signed URLs, public buckets produce plain ones.

## HTTP Request

`POST` `{API_URL}/object-storage/buckets/toggle-privacy`

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

## Body Parameters

| Parameter             | Requirement | Type      | Description                                             |
| --------------------- | ----------- | --------- | ------------------------------------------------------- |
| `object_storage_name` | Required    | `string`  | The workspace holding the bucket                        |
| `bucket_name`         | Required    | `string`  | The bucket to toggle                                    |
| `team_id`             | Optional    | `integer` | Act on a team's storage. See [Teams](/account/teams.md) |

## Response Attributes

#### data `dict`

The result of the toggle:

* **bucket\_name** `string`: The bucket that was toggled.
* **new\_private** `string`: The state the bucket is now in — `"1"` for private, `"0"` for public.
* **status\_code** `integer`: The provider's status code. Anything other than `200` means the toggle did not take effect.
* **error** `string`: The provider's error, or `null` on success.
* **ret** `object`: The provider's raw response.

#### status `string`

`success` or `failed`.

#### message `string`

A description of the result.

> **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/buckets/toggle-privacy' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"object_storage_name": "research-datasets", "bucket_name": "checkpoints"}'
```

#### Response

```json
{
    "data": {
        "bucket_name": "checkpoints",
        "new_private": "1",
        "status_code": 200,
        "error": null,
        "ret": {}
    },
    "message": "Bucket privacy toggled successfully",
    "status": "success"
}
```

> **Note:** Switching a bucket to private also triggers a CDN refresh, so a URL that was publicly reachable may take a moment to stop resolving.

## See also

* [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md)
* [Get Download URL](/api-reference/platform-api/list-workspaces/get-download-url.md)