Clatter Labs
Console

Code Buckets

Create a backup

View as Markdown

Snapshot a bucket's code and stored files.

POSTapi.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/backupsbackups:write

Captures the bucket's current code tree and the list of its stored zips and assets. The Free tier keeps 1 backup per account: send "replace": true to replace it.

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

bucket_idstringrequired

The bucket id (cbk_…).

Body

application/json

namestring

Up to 80 characters. Defaults to Backup <date> UTC.

replacebooleandefault: false

On the Free tier, replace your existing backup instead of failing with 409 backup_limit.

Response

201 · application/json

objectstring

Always backup.

idstring

The backup id (cbb_…).

bucket_id / project_idstring

Where it was taken.

namestring

Its name.

code_refstring | null

The code tree it captured (null if the bucket had no code yet).

objectsinteger

How many stored zips and assets it covers.

filesinteger

Files in the captured code tree.

bytesinteger

Total size of the stored files it covers.

created_atstring

ISO 8601 timestamp.

Errors

StatusCodeWhen
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 bucket with that id on your account.
409backup_limitYour plan's backups are used; error.existing_backup_id names the one to replace.
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/backups" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Before checkout rewrite",
    "replace": 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/buckets/BUCKET_ID/backups",
    headers=headers,
    json={
        "name": "Before checkout rewrite",
        "replace": 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/buckets/BUCKET_ID/backups", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "name": "Before checkout rewrite",
    "replace": true
  }),
});
console.log(await res.json());
{
  "object": "backup",
  "id": "cbb_h3g7f1d9s5a2q8w4e6r0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
  "name": "Before checkout rewrite",
  "code_ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
  "objects": 2,
  "files": 1284,
  "bytes": 131204115,
  "created_at": "2026-10-28T14:05:11.482Z"
}