> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudservices.ecowestern.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage ClearLake buckets

> Choose bucket names, visibility, and lifecycle operations

Bucket routes use an ECS API key with the permission shown for each operation.

## Bucket names

Names must:

* Be 2 to 63 characters.
* Use lowercase letters, numbers, and hyphens.
* Start and end with a letter or number.
* Be unique within your account.

Valid examples include `user-uploads`, `media-assets`, and `backup-2026`.

## Create a bucket

`POST /clearlake/buckets` requires `clearlake:write`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "user-uploads",
  "visibility": "private"
}
```

`visibility` defaults to `private`. Use `public` for assets that may be served without private access controls.

Visibility cannot be changed after creation. To change it, create a new bucket and move the objects.

## List and inspect

* `GET /clearlake/buckets` requires `clearlake:read` and returns `{ "buckets": [...] }`.
* `GET /clearlake/buckets/:name` requires `clearlake:read` and returns one bucket.

Use the bucket name from the response in later object routes.

## Delete a bucket

`DELETE /clearlake/buckets/:name` requires `clearlake:delete` and returns `204 No Content`.

Deleting a bucket is permanent and removes its contents. Confirm the bucket name before issuing the request.

## Choosing visibility

| Visibility | Best for                                       | Access pattern                          |
| ---------- | ---------------------------------------------- | --------------------------------------- |
| `private`  | User data, backups, and application files      | Short-lived download URLs               |
| `public`   | Website assets, public media, and shared files | Download URLs or Waymark custom domains |