Clatter Labs
Console

Code Buckets

Create a bucket

View as Markdown

Add a bucket to a project.

POSTapi.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/bucketsbuckets: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

Authorizationstringrequired

Your API key as a bearer token: Bearer clsk_.... Create keys in the Console with the Code Buckets permissions you need.

X-Clatter-Accountstringrequired

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_idstringrequired

The Project ID (cbp_…).

Body

application/json

namestringrequired

Up to 80 characters.

descriptionstring

Up to 500 characters.

previewbooleandefault: true

Unpack uploaded zips into a browsable code tree. false keeps code only in encrypted archives.

Response

201 · application/json

objectstring

Always bucket.

idstring

The bucket id, like cbk_q7c1r9t2y6u0i3o8p5a4.

project_idstring

The Project ID it belongs to.

name / descriptionstring

Your name and description.

previewboolean

Whether uploaded zips are unpacked into a browsable code tree.

visibilitystring

private (default) or public. In a public bucket, every stored file that follows the bucket default has a public link. See Public files.

codeobject

{ ref, files, bytes }: the current code tree. ref is null until the first zip is unpacked.

storageobject

{ 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).

encryptionobject

How stored files are encrypted.

created_at / updated_atstring

ISO 8601 timestamps.

Errors

StatusCodeWhen
400bad_requestname is missing or too long.
401invalid_api_key / missing_account_id / account_mismatchThe key or Account ID is wrong.
402quota_exceededThis month's free tokens are used up.
403insufficient_scopeThe key lacks the permission.
404not_foundNo project with that id on your account.
409limit_reachedThe project already has 100 buckets.
503storage_unavailableStorage couldn't be set up; try again.
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
  }'
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}

r = requests.post(
    "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets",
    headers=headers,
    json={
        "name": "web",
        "preview": True
    },
)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
  "Content-Type": "application/json",
};

const res = await fetch("https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "name": "web",
    "preview": true
  }),
});
console.log(await res.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"
}