# Create a backup

> Snapshot a bucket's code and stored files.

`POST https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/backups` (key permission: `backups: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

- `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

- `bucket_id` (string, required): The bucket id (`cbk_…`).

## Body

- `name` (string): Up to 80 characters. Defaults to `Backup <date> UTC`.
- `replace` (boolean, default false): On the Free tier, replace your existing backup instead of failing with `409 backup_limit`.

## Response

- `object` (string): Always `backup`.
- `id` (string): The backup id (`cbb_…`).
- `bucket_id / project_id` (string): Where it was taken.
- `name` (string): Its name.
- `code_ref` (string | null): The code tree it captured (`null` if the bucket had no code yet).
- `objects` (integer): How many stored zips and assets it covers.
- `files` (integer): Files in the captured code tree.
- `bytes` (integer): Total size of the stored files it covers.
- `created_at` (string): ISO 8601 timestamp.

## Example request

```bash
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
  }'
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `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 bucket with that id on your account. |
| `409` | `backup_limit` | Your plan's backups are used; `error.existing_backup_id` names the one to replace. |

## Example response

```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"
}
```