# Backups

Source: https://docs.bearletter.com/api/backup

Your blog is yours. Besides the downloads in the dashboard, the text API exports everything, so a script can keep your own copy up to date: on your computer, a server, or a GitHub repository.

## A backup token

Create a token in **Settings › Apps & tokens** and choose **Backup (read only)**. It can read and export but never change anything. Tick **Include subscribers' email addresses** only if the backup should hold your list; those are your readers' addresses. **Rotate** gives the token a new secret whenever you like.

## What to fetch

All addresses start with `https://api.bearletter.com/v1` and take `Authorization: Bearer bl_…`.

| Request | Gives |
| --- | --- |
| `GET /export/blog.zip` | The blog folder: every post, page, episode and site file as published, drafts included (unpublished changes to a published file are not). It imports back in **Settings › Backup**. |
| `GET /export/subscribers.csv` | Your list as CSV (`?status=active`, `pending` or `unsubscribed`). Needs a token that includes subscribers. |
| `GET /export/media` | Every file in your media library with its public `url`. |

Media files are not sent through the API: download each from its `url`. A file's address never changes, so fetch only the ones you do not have yet.

## A script

This keeps a folder up to date. Run it by hand, from cron, or in a scheduled job.

```sh
#!/bin/sh
set -eu
: "${BEARLETTER_TOKEN:?set BEARLETTER_TOKEN to a backup token}"
API=https://api.bearletter.com/v1
AUTH="Authorization: Bearer $BEARLETTER_TOKEN"
OUT=${1:-bearletter-backup}
mkdir -p "$OUT/media"

curl -fsS -H "$AUTH" "$API/export/blog.zip" -o "$OUT/blog.zip"

# Media: download only what is new, straight from its public address.
curl -fsS -H "$AUTH" "$API/export/media" | jq -r '.files[] | [.path, .url] | @tsv' |
while IFS="$(printf '\t')" read -r path url; do
  [ -f "$OUT/media/$path" ] && continue
  mkdir -p "$(dirname "$OUT/media/$path")"
  curl -fsS "$url" -o "$OUT/media/$path"
done
```

It needs `curl` and `jq`. Keep the token in an environment variable or your scheduler's secrets, never in the script or a repository.

### Every night with cron

```text
0 3 * * * BEARLETTER_TOKEN=bl_… /home/you/bearletter-backup.sh /home/you/backups/blog
```

### Every night with GitHub Actions

Put the script in a private repository as `backup.sh`, add the token as the secret `BEARLETTER_TOKEN`, and commit the result:

```yaml
name: Back up Bearletter
on:
  schedule: [{ cron: "0 3 * * *" }]
  workflow_dispatch: {}
jobs:
  backup:
    runs-on: ubuntu-latest
    permissions: { contents: write }
    steps:
      - uses: actions/checkout@v4
      - run: sh backup.sh backup
        env: { BEARLETTER_TOKEN: "${{ secrets.BEARLETTER_TOKEN }}" }
      - run: |
          git config user.name "backup"
          git config user.email "backup@users.noreply.github.com"
          git add backup && git commit -m "Backup $(date -u +%F)" || exit 0
          git push
```

A git repository also keeps every earlier version of your files.
