API
Backups
Export everything to your own disk or storage on a schedule, with a read-only token. Works on every plan.
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.
#!/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#
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:
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.
Bearletter · bearletter.com · Every page is also Markdown: llms.txt