# Backups

> Snapshot a bucket's code and stored files, and bring it back in one step.

A **backup** captures two things about a bucket:

- its **code tree** (the current `ref`), and
- the list of its **stored objects** (zips and assets).

## Create a backup

```bash
curl $CB/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"}'
```

Backups need the `backups:write` permission. Taking one is quick: nothing is copied, the backup points at the stored data, which stays as long as the backup exists.

## Restore

```bash
curl -X POST $CB/v1/backups/BACKUP_ID/restore \
  -H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

Restoring:

1. puts the backup's code tree back as a **new version** of the tree. The version you had before stays reachable by its ref (it's in the `code.updated` and `backup.restored` events), so a restore never destroys work;
2. brings back stored objects from the backup that were deleted since;
3. by default keeps objects added after the backup. Send `{"objects": "exact"}` to hide those too, so the stored files match the backup exactly.

A `backup.restored` event records what happened.

## How many backups

| Plan | Backups |
| --- | --- |
| Free | 1 per account (across all buckets) |
| Need more? | [Contact us](https://help.clatterlabs.com/code-buckets/troubleshooting/cb-contact-support) |

On the Free tier, creating a second backup answers `409 backup_limit` with the id of the one you have. Send `"replace": true` to replace it, or [delete it](/api-reference/code-buckets/backups/delete) first. Restoring is free and unlimited.