BearletterDocsllms.txtbearletter.comDashboard

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_….

RequestGives
GET /export/blog.zipThe 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.csvYour list as CSV (?status=active, pending or unsubscribed). Needs a token that includes subscribers.
GET /export/mediaEvery 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