# Create a bucket

> Add a bucket to a project.

`POST https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/buckets` (key permission: `buckets:write`)

Creates an empty bucket with its own encryption key. A project can have up to 100 buckets; each holds up to 10 GB.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Path parameters

- `project_id` (string, required): The Project ID (`cbp_…`).

## Body

- `name` (string, required): Up to 80 characters.
- `description` (string): Up to 500 characters.
- `preview` (boolean, default true): Unpack uploaded zips into a browsable code tree. `false` keeps code only in encrypted archives.

## Response

- `object` (string): Always `bucket`.
- `id` (string): The bucket id, like `cbk_q7c1r9t2y6u0i3o8p5a4`.
- `project_id` (string): The Project ID it belongs to.
- `name / description` (string): Your name and description.
- `preview` (boolean): Whether uploaded zips are unpacked into a browsable code tree.
- `visibility` (string): `private` (default) or `public`. In a public bucket, every stored file that follows the bucket default has a public link. See [Public files](/code-buckets/public-files).
- `code` (object): `{ ref, files, bytes }`: the current code tree. `ref` is `null` until the first zip is unpacked.
- `storage` (object): `{ used_bytes, pending_bytes, limit_bytes }`. `used_bytes` counts stored zips and assets; `pending_bytes` is reserved by unfinished uploads; the limit is 10 GB (10,737,418,240 bytes).
- `encryption` (object): How stored files are encrypted.
- `created_at / updated_at` (string): ISO 8601 timestamps.

## Example request

```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "preview": true
  }'
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `name` is missing or too long. |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `quota_exceeded` | This month's free tokens are used up. |
| `403` | `insufficient_scope` | The key lacks the permission. |
| `404` | `not_found` | No project with that id on your account. |
| `409` | `limit_reached` | The project already has 100 buckets. |
| `503` | `storage_unavailable` | Storage couldn't be set up; try again. |

## Example response

```json
{
  "object": "bucket",
  "id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
  "name": "web",
  "description": null,
  "preview": true,
  "visibility": "private",
  "code": {
    "ref": null,
    "files": 0,
    "bytes": 0
  },
  "storage": {
    "used_bytes": 0,
    "pending_bytes": 0,
    "limit_bytes": 10737418240
  },
  "encryption": {
    "algorithm": "AES-256-GCM",
    "key": "per-bucket data key, wrapped by a Clatter Labs master key"
  },
  "created_at": "2026-10-28T14:05:11.482Z",
  "updated_at": "2026-10-28T14:05:11.482Z"
}
```