Backups

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

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

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

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 first. Restoring is free and unlimited.