Clatter Labs
Console

Code Buckets

Restore a backup

View as Markdown

Bring a bucket back to a backup.

POSTapi.codebuckets.clatterlabs.xyz/v1/backups/{backup_id}/restorebackups:write

Puts the backup's code tree back as a new version (the current one stays reachable by its ref) and brings back stored files from the backup that were deleted since. By default files added after the backup are kept; send "objects": "exact" to hide them too. Recorded as a backup.restored event.

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

backup_idstringrequired

The backup id (cbb_…).

Body

application/json

objectsstringdefault: keep

keep leaves newer files in place; exact makes the stored files match the backup.

Response

200 · application/json

objectstring

restore.

backup_id / bucket_idstring

What was restored.

code_refstring | null

The new current code ref.

objectsobject

{ mode, revived, hidden }: how many stored files came back or were hidden.

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 backup with that id on your account.
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/backups/BACKUP_ID/restore" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "objects": "keep"
  }'
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/backups/BACKUP_ID/restore",
    headers=headers,
    json={
        "objects": "keep"
    },
)
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/backups/BACKUP_ID/restore", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "objects": "keep"
  }),
});
console.log(await res.json());
{
  "object": "restore",
  "backup_id": "cbb_h3g7f1d9s5a2q8w4e6r0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "code_ref": "3e8d0b7c4a1f9b1f0c5e2a7d43e8b6c1f0a9d2e5",
  "objects": {
    "mode": "keep",
    "revived": 1,
    "hidden": 0
  }
}