# Restore a backup

> Bring a bucket back to a backup.

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

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

- `backup_id` (string, required): The backup id (`cbb_…`).

## Body

- `objects` (string, default keep): `keep` leaves newer files in place; `exact` makes the stored files match the backup.

## Response

- `object` (string): `restore`.
- `backup_id / bucket_id` (string): What was restored.
- `code_ref` (string | null): The new current code ref.
- `objects` (object): `{ mode, revived, hidden }`: how many stored files came back or were hidden.

## Example request

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

## 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 backup with that id on your account. |

## Example response

```json
{
  "object": "restore",
  "backup_id": "cbb_h3g7f1d9s5a2q8w4e6r0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "code_ref": "3e8d0b7c4a1f9b1f0c5e2a7d43e8b6c1f0a9d2e5",
  "objects": {
    "mode": "keep",
    "revived": 1,
    "hidden": 0
  }
}
```