# Bearletter Docs

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

A Bearletter blog is a folder of plain text: Markdown articles and pages with a few properties at the top, some site files for the menu and footer, a handful of components, and one stylesheet. People edit it in the dashboard; scripts and AI agents can read and change the same files.

```text
Set up Bearletter for me and help me work on my blog.

1. Read https://docs.bearletter.com/llms.txt, then open only the pages you need. Every page is Markdown.
2. Know the blog's rules before writing: the site files have fixed names (home.md, nav.md, directories.md, redirects.md, social.md, blogroll.md, footer.md, post-header.md, post-footer.md, post-aside.md, styles.css, podcast.md) that you never rename or add to; only files under posts/ and pages/ are yours to name.
3. Add the Bearletter MCP server to your own configuration: a remote (HTTP) server named bearletter at https://api.bearletter.com/mcp. Use your own way of adding MCP servers (a command or your config file). If you cannot change your own settings, tell me exactly where I add it. There is no key to copy.
4. If you take skills, also install the Bearletter skill: https://docs.bearletter.com/skills/bearletter/SKILL.md (how: https://docs.bearletter.com/mcp/skills.md).
5. When you first use the server, it opens a Bearletter page in my browser. I will sign in and approve it.
6. Check the connection by calling get_blog, and tell me my blog's title and address.
7. From then on, read before you change anything, tell me what you will change, and wait for my yes before saving anything that goes public. If a save is refused, fix the lines it names and try again.
```

## Read these docs as an agent

- [llms.txt](/llms.txt) lists every page with its Markdown address and a one-line summary. Start there and open only what you need.
- Every page is also Markdown: add `.md` to its address, or send `Accept: text/markdown`.
- [llms-full.txt](/llms-full.txt) holds all pages in one file.

## Pages

### Agents (MCP)

- [Connect an agent](/mcp/connect): Add Bearletter as a remote MCP server, approve it in the browser, and check that it works.
- [Tools](/mcp/tools): Every MCP tool by area, what it does and the permission it needs.
- [Skills and plugins](/mcp/skills): The Bearletter skill and plugin, which add the MCP server and teach your agent how Bearletter works.

### Blog format

- [The blog folder](/blog/folder): Which files a blog has, where posts, pages and episodes go, and how a path becomes an address.
- [Properties](/blog/frontmatter): The key: value block at the top of a file, and every property each file accepts.
- [Components](/blog/components): The lines that start with :: and what each one shows.
- [Themes](/blog/themes): How styles.css is laid out, the variables themes share, light and dark modes, and the page's class names.
- [Podcast](/blog/podcast): The podcast (Pro): podcast.md for the show and one file per episode in podcast/, with every property.

### API

- [Text API](/api/text-api): Read and write blog files over HTTPS with a personal access token. Reading works on every plan; writing is part of Pro.
- [Backups](/api/backup): Export everything to your own disk or storage on a schedule, with a read-only token. Works on every plan.


---

# Connect an agent

Source: https://docs.bearletter.com/mcp/connect

Bearletter is a remote MCP server. Agents that speak MCP (Claude, Codex, Cursor and others) can read and change your blog with the same rules as the dashboard.

```text
https://api.bearletter.com/mcp
```

## Let your agent do it

Agents that can run commands or edit their settings add Bearletter themselves; chat apps tell you where to click.

```text
Set up Bearletter for me and help me work on my blog.

1. Read https://docs.bearletter.com/llms.txt, then open only the pages you need. Every page is Markdown.
2. Know the blog's rules before writing: the site files have fixed names (home.md, nav.md, directories.md, redirects.md, social.md, blogroll.md, footer.md, post-header.md, post-footer.md, post-aside.md, styles.css, podcast.md) that you never rename or add to; only files under posts/ and pages/ are yours to name.
3. Add the Bearletter MCP server to your own configuration: a remote (HTTP) server named bearletter at https://api.bearletter.com/mcp. Use your own way of adding MCP servers (a command or your config file). If you cannot change your own settings, tell me exactly where I add it. There is no key to copy.
4. If you take skills, also install the Bearletter skill: https://docs.bearletter.com/skills/bearletter/SKILL.md (how: https://docs.bearletter.com/mcp/skills.md).
5. When you first use the server, it opens a Bearletter page in my browser. I will sign in and approve it.
6. Check the connection by calling get_blog, and tell me my blog's title and address.
7. From then on, read before you change anything, tell me what you will change, and wait for my yes before saving anything that goes public. If a save is refused, fix the lines it names and try again.
```

## Or add it yourself

Any agent that supports the Model Context Protocol works: add the address above as a **remote MCP server** (HTTP). There is no key to copy. The first time the agent uses Bearletter, it finds the sign-in page by itself and opens it in your browser.

| Agent | How to add it |
| --- | --- |
| Claude Code | `claude mcp add --transport http bearletter https://api.bearletter.com/mcp`, then `/mcp` to sign in |
| Claude (web and desktop) | Customize › Connectors › Add custom connector |
| ChatGPT | Settings for apps and MCP servers › add a custom MCP server, with OAuth |
| Codex | `[mcp_servers.bearletter]` with `url = "https://api.bearletter.com/mcp"` in `~/.codex/config.toml`, then `codex mcp login bearletter` |
| OpenCode | `"mcp": { "bearletter": { "type": "remote", "url": "https://api.bearletter.com/mcp" } }` in `opencode.json` |
| Cursor | `"mcpServers": { "bearletter": { "url": "https://api.bearletter.com/mcp" } }` in `~/.cursor/mcp.json` |
| VS Code | `"servers": { "bearletter": { "type": "http", "url": "https://api.bearletter.com/mcp" } }` in `.vscode/mcp.json` |
| Gemini CLI | `gemini mcp add --transport http bearletter https://api.bearletter.com/mcp` |

For the technically curious: Bearletter answers an unauthenticated request with the standard pointer to its OAuth authorization server, and accepts both client metadata documents and dynamic client registration, so agents need nothing configured beyond the address.

## Approve it

The first time the agent uses Bearletter, it opens a Bearletter page in your browser. Sign in, check what the agent asks to do, untick anything you do not want, and choose **Allow**. Reading your subscribers' email addresses is off unless you tick it.

| Permission | Lets the agent |
| --- | --- |
| `read` | Read your blog, drafts and stats |
| `write` | Write, publish and delete posts, pages and episodes |
| `media` | Upload files to your media library |
| `blog` | Change your blog's home page, menu, theme and settings |
| `subscribers` | See and export your subscribers' email addresses |

Changing the blog from an agent needs Pro, as in the dashboard. If the agent later needs a permission you left out, it asks, and you approve it the same way.

## Check it

Ask the agent to call `get_blog`. It answers with your blog's title and address.

## Stay in control

- The agent's access lasts until you remove it: **Settings › Apps & tokens** shows every connected assistant, with **Disconnect**.
- Access renews itself while you use it, and ends after 30 days without use.
- Anything an agent publishes is live at once, like in the dashboard. Good agents tell you what they will change first; the prompt on the [home page](/) asks them to.


---

# Tools

Source: https://docs.bearletter.com/mcp/tools

Each tool does one thing and runs as you, with the same checks, plans and limits as the dashboard. A tool that needs a permission the agent was not given asks for it.

Tools that read are marked read-only; tools that change something public are marked so agents can ask you first.

## Docs and blog

| Tool | Does | Permission |
| --- | --- | --- |
| `get_blog_guide` | Reads these docs: the index, or a page by its path. | none |
| `get_blog` | The blog's title, address, time zone and plan. | `read` |
| `update_blog_settings` | Language, time zone, visit counts, AI training, address. | `blog` |

## Blog files

The site files have fixed names; only files under `posts/`, `pages/` and `podcast/` are created, renamed or moved. See [The blog folder](/blog/folder).

| Tool | Does | Permission |
| --- | --- | --- |
| `list_blog_files` | Files in the folder; `kind` is `post`, `page`, `episode` or `site`. | `read` |
| `read_blog_file` | One file with its content, its unpublished changes and `writeSeq`. | `read` |
| `save_blog_file` | Creates or replaces a file as readers see it. | `write`; `blog` for site files |
| `move_blog_file` | Renames or moves a post, page or episode; a public post or page keeps its old address. | `write` |
| `delete_blog_file` | Deletes a file with its revisions. | `write`; `blog` for site files |

## Write

A draft is a post, page or episode with `publish: false`. Editing a published file keeps what readers see and stores the edit as unpublished changes until it is published.

| Tool | Does | Permission |
| --- | --- | --- |
| `create_draft` | A new private draft: a post, a page or a podcast episode. | `write` |
| `save_draft` | Saves a draft, or a published file's unpublished changes. | `write` |
| `preview_file` | A 30-minute link showing a file with its changes as it would look. | `read` |
| `publish_file` | Publishes a draft or a file's unpublished changes, now or at a time. | `write` |
| `unpublish_file` | Takes a published or scheduled file back to a draft. | `write` |
| `discard_changes` | Drops a published file's unpublished changes. | `write` |

## Look

| Tool | Does | Permission |
| --- | --- | --- |
| `list_themes` | The built-in themes and the current appearance. | `read` |
| `preview_styles` | A 30-minute link showing the blog with a theme or a new stylesheet. | `read` |
| `apply_theme` | Replaces `styles.css` with a built-in theme. | `blog` |
| `set_appearance` | Accent color, text width, font, size. | `blog` |

## Media

Files never pass through the tools: they are downloaded from their public address and uploaded straight to storage.

| Tool | Does | Permission |
| --- | --- | --- |
| `list_media` | Files with their public address and how often they are used. | `read` |
| `start_media_upload` | Reserves a file and returns an address to upload it to with HTTP PUT. | `media` |
| `finish_media_upload` | Checks the uploaded file and adds it to the library. | `media` |

## Subscribers and stats

| Tool | Does | Permission |
| --- | --- | --- |
| `list_subscribers` | Subscribers and counts, 50 at a time. | `subscribers` |
| `export_subscribers` | The list as CSV. | `subscribers` |
| `add_subscriber` | Adds one address, as you would by hand. | `subscribers` |
| `get_blog_stats` | Visits by day, top posts and referrers. | `read` |

## How tools behave

- Read before you write: every change passes back the `writeSeq` that was read. If the file changed since, the change is refused; read it again.
- A refused save says which lines to fix, in the same words as the dashboard.
- Preview, then apply: `preview_styles` and `preview_file` give you a link to look at first.
- Results are JSON text.


---

# Skills and plugins

Source: https://docs.bearletter.com/mcp/skills

The MCP server alone is enough to work on your blog. The Bearletter skill adds the blog's rules and the usual ways of doing things (preview before publishing, the fixed file names, drafts and unpublished changes), so the agent gets them right the first time.

The skill and the plugin are served here, and mirrored on GitHub at [devxiyang/bearletter-agents](https://github.com/devxiyang/bearletter-agents):

| File | For |
| --- | --- |
| [/skills/bearletter/SKILL.md](/skills/bearletter/SKILL.md) | The skill itself: one Markdown file. |
| [/skills/bearletter.zip](/skills/bearletter.zip) | The skill as a zip, for apps that take an upload. |
| [/agents.zip](/agents.zip) | The whole plugin folder: the skill plus the MCP server for Claude Code, Codex and Gemini CLI. |

The [prompt on the home page](/) asks your agent to install the skill when it can.

## Install

| Agent | How |
| --- | --- |
| Any agent with skills | Save `https://docs.bearletter.com/skills/bearletter/SKILL.md` as `bearletter/SKILL.md` in its skills folder (many read `.agents/skills/`; Claude Code reads `.claude/skills/`), and add the MCP server ([Connect](/mcp/connect)). |
| Claude Code | `/plugin marketplace add devxiyang/bearletter-agents`, then `/plugin install bearletter@bearletter`, which adds the MCP server and the skill. Without GitHub: unzip `/agents.zip` and run `/plugin marketplace add ./bearletter-agents`. |
| Gemini CLI | `gemini extensions install https://github.com/devxiyang/bearletter-agents`, or unzip `/agents.zip` and install that folder. |
| Codex | Install the plugin folder from `/agents.zip` (it has `plugin.json`, `mcp.json` and `skills/`). |
| Claude (web and desktop) | Upload `/skills/bearletter.zip` under Customize › Skills, and add the MCP server as a connector. |

The skill is under the MIT license.


---

# The blog folder

Source: https://docs.bearletter.com/blog/folder

Every blog is one folder. Only these files can exist in it:

| File | What it holds |
| --- | --- |
| `home.md` | The home page: its title and text. Usually lists posts with `::posts`. |
| `nav.md` | The menu: one Markdown link per line, at most 20. |
| `footer.md` | Text at the bottom of every page. |
| `post-header.md`, `post-footer.md`, `post-aside.md` | Parts shown above, below or beside every post. |
| `social.md` | Links to your other profiles, one Markdown link per line. |
| `blogroll.md` | Blogs you recommend, one per line. See [Blogroll](#blogroll). |
| `directories.md` | Display names and order for folders of posts. |
| `redirects.md` | Old addresses and where they go now. |
| `podcast.md` | The podcast's show (Pro). See [Podcast](/blog/podcast). |
| `styles.css` | The blog's whole stylesheet. See [Themes](/blog/themes). |
| `posts/…/*.md` | Articles, listed by date, in feeds and on the fediverse. |
| `pages/…/*.md` | Pages such as About or Now: addressed, not listed. |
| `podcast/*.md` | Podcast episodes (Pro), at `/podcast/<name>`. |

**These names are fixed.** Do not rename the site files, move them into folders, or create other files beside them: the blog reads exactly these. Only files under `posts/`, `pages/` and `podcast/` take names of your choosing. A file can be at most 1 MB. Anything else is refused, with the line that needs fixing.

## Addresses

An article or page is served at its path without the top folder and `.md`:

- `posts/reading-slowly.md` → `/reading-slowly`
- `posts/trips/rome.md` → `/trips/rome`, and the folder gets a listing at `/trips`
- `pages/about.md` → `/about`

File and folder names use letters and digits of any language, plus `_ . ~ -`. A path has at most 32 folders.

The blog keeps these addresses for itself: `/archive`, `/feed`, `/rss.xml`, `/feed.json` (also under `/tags/<tag>/`), `/rss`, `/sitemap.xml`, `/robots.txt`, `/blogroll.opml`, `/.well-known/…` and `/podcast…`.

## Links files

`nav.md`, `social.md` and `directories.md` hold only Markdown links, one or more per line:

```md
[About](/about)
[Archive](/archive)
[Notes](https://notes.example.com)
```

Menu links use `https://`. Links to other sites in the menu need Pro.

In `directories.md`, the link's address is the folder and its text is the name: `[Travel](/trips)`.

## Blogroll

`blogroll.md` lists the blogs you read, one per line, in the order shown: the blog's name linked to its address, its feed as a second link named `feed` when it has one, then a few words about it if you like.

```md
[Ana's notes](https://ana.example/) [feed](https://ana.example/feed.xml) Gardens and code.
[Ben writes](https://ben.example/)
```

Blog › Home › Blogroll fills these lines in for you: type a blog's address and it finds the name and the feed. A blogroll holds at most 200 blogs.

Place `::blogroll` on any page to show the list. While it has blogs, feed readers can follow them all from `/blogroll.opml` (also at `/.well-known/recommendations.opml`), and every page links to it with `<link rel="blogroll">`.

## Redirects

`redirects.md` has one redirect per line: the old address, a space, then a path on this blog or an `https://` address.

```text
/2019/hello /hello
/old-about https://example.com/about
```

To keep a single article's old addresses, use its `alias` property instead (see [Properties](/blog/frontmatter)).

## Drafts and unpublished changes

A post, page or episode with `publish: false` is a draft: it has no address and nobody else sees it. Write creates drafts this way.

Once a file is published, edits made in Write are kept as unpublished changes beside it: readers see the published text until you choose **Publish changes**, or the changes are discarded. Every publish keeps a revision of the file, which you can restore later.


---

# Properties

Source: https://docs.bearletter.com/blog/frontmatter

A file may start with a block of properties between two lines of `---`, one `key: value` per line:

```md
---
title: Reading slowly
published_date: 2026-10-02 09:30
tags: books, habits
---
One page a day is still a book a year.
```

Keys are lower case. A file that does not start with `---` has no properties. An unknown key, or a value in the wrong form, is refused with its line number.

## Articles (`posts/`) and pages (`pages/`)

| Property | Value |
| --- | --- |
| `title` | Required. Up to 300 characters. |
| `published_date` | `2026-10-02` or `2026-10-02 09:30`, in the blog's time zone. A future date schedules it. |
| `tags` | Comma-separated, at most 20, each up to 60 characters. |
| `publish` | `false` keeps it offline. |
| `alias` | Old addresses, comma-separated paths such as `/old-name`, at most 10. |
| `canonical_url` | Where the original lives, if it was first published elsewhere. |
| `meta_description` | The summary for search and sharing. Without it, the first paragraph is used. |
| `meta_image` | The image for sharing. Without it, a card is generated. |
| `lang` | A language code such as `en` or `zh-CN`, when it differs from the blog's. |
| `class_name` | Extra class names for the page's `<body>`, for styling one article. |
| `make_discoverable` | `false` keeps it off the front page. |

Articles also take:

| Property | Value |
| --- | --- |
| `post_header`, `post_footer`, `post_aside` | `false` hides that part on this article. |
| `pinned` | `true` pins it on the blog's fediverse profile. |

`true` and `false` are written exactly so.

## `home.md`

| Property | Value |
| --- | --- |
| `title` | Required. The blog's name, up to 200 characters. |
| `seo_title` | A different title for search results. |
| `meta_description` | The blog's summary for search, sharing and feeds. |
| `meta_image` | The image for sharing. |
| `favicon` | The icon's address. |

## Site parts

| File | Properties |
| --- | --- |
| `footer.md` | `enabled`, `powered_by` (`false` hides the Bearletter credit; Pro) |
| `post-header.md`, `post-footer.md`, `post-aside.md` | `enabled` |

`nav.md`, `social.md`, `blogroll.md`, `directories.md`, `redirects.md` and `styles.css` have no properties.

## Markdown

Bodies are CommonMark with GitHub tables, strikethrough and footnotes. HTML is allowed and cleaned; on Free, `<style>` elements and `style` attributes are removed, on Pro they are kept.


---

# Components

Source: https://docs.bearletter.com/blog/components

A component is a line of its own that starts with `::`, optionally with settings in braces:

```md
::posts{limit="10" tag="books"}
```

Components work in `home.md`, pages, posts, `footer.md` and the post parts. A known component with a wrong setting is refused; an unknown one is kept as written.

| Component | Shows | Settings |
| --- | --- | --- |
| `::posts` | A list of articles, newest first. | `limit` (1–1000), `tag`, `folder` (a folder under `posts/`) |
| `::tags` | Every tag, linked to the archive filtered by it. | none |
| `::social` | The links from `social.md`, with icons. | none |
| `::blogroll` | The blogs in `blogroll.md`, with a link to follow them all. | none |
| `::subscribe` | The email sign-up form, while the blog's list is collecting subscribers (Pro). | none |
| `::reply` | A "Reply by email" link for the post it is in. | none |
| `::podcast` | The latest podcast episodes (Pro). | `limit` (1–1000) |

Write settings in double quotes. A component with nothing to show (no posts, no tags) leaves no trace on the page.

## Examples

A home page that lists the ten latest posts:

```md
---
title: Morning Pages
---
Notes on reading slowly and small websites.

::posts{limit="10"}
```

A footer on every post that invites replies:

```md
---
enabled: true
---
::reply
```


---

# Themes

Source: https://docs.bearletter.com/blog/themes

The whole look of a blog is `styles.css`. Choosing a theme in the dashboard replaces this file with the theme's stylesheet; after that it is yours. Editing it needs Pro.

## Variables

Every built-in theme starts with one `:root` block of variables. The dashboard's Appearance controls change `--accent`, `--width`, `--font-body` and `--font-size` there and leave the rest alone, so keep that block first.

```css
:root {
  --width: 760px;
  --font-body: Georgia, "Songti SC", serif;
  --font-heading: var(--font-body);
  --font-size: 18px;
  --bg: #fffdf8;
  --text: #2e2b3a;
  --heading: #1d1b26;
  --link: #1d1b26;
  --muted: #4a4658;
  --rule: #e2ddcf;
  --code-bg: #f3efe3;
  --accent: #4b3fd1;
}
```

Themes may add their own variables (Bold has `--band` and `--marker`; Poster has `--panel` and `--accent-text`).

## Light and dark

A theme follows the reader's system. Put the dark values in a media query after the first block:

```css
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #17151f;
    --text: #e4e0d6;
    --heading: #fffdf8;
    --link: #fffdf8;
  }
}
```

A color used for text on a fill (such as dark ink on a yellow button) can stay the same in both modes.

## Page structure

Every page has the same frame:

```html
<body class="post">
  <header class="site-header">
    <a class="title" href="/">Blog name</a>
    <nav class="site-nav">…</nav>
  </header>
  <main>…</main>
  <footer class="site-footer">…</footer>
  <p class="powered-by">…</p>
</body>
```

The body's class says what the page is: `home`, `post`, `page`, `archive`, `directory`, `not-found`, `podcast-show`, plus an article's own `class_name`.

Class names worth styling:

- Lists: `.blog-posts`, `.post-date`, `.post-title`, `.post-description`
- Articles: `.post-meta`, `.tags`, `.post-header`, `.post-footer`, `.sidebar`, `.content`
- Archive: `.archive-filters`, `.archive-search`, `.topic-links`, `.search-status`
- Components: `.subscribe`, `.reply-by-email`, `.social`, `.like-button`
- Podcast: `.podcast-header`, `.podcast-cover`, `.podcast-player`, `.player-play`, `.player-seek`, `.podcast-subscribe`, `.episode-list`, `.episode-title`, `.episode-meta`

Elements inside articles are plain HTML (`h1`–`h4`, `p`, `blockquote`, `pre`, `code`, `table`, `img`, `hr`), so style them by tag.

## Checking a change

Try a stylesheet before saving it: the dashboard's theme cards open a preview of your own blog with that theme, and nothing changes until you choose it.


---

# Podcast

Source: https://docs.bearletter.com/blog/podcast

The podcast is part of the blog folder, with Pro: `podcast.md` for the show and `podcast/<name>.md` for each episode. Episodes are written, previewed and published in Write like posts. An episode's name is also its address: `podcast/first-words.md` is `/podcast/first-words`. Names use letters, digits, `_` and `-`.

The show's page is `/podcast`, its feed (for Apple Podcasts, Spotify and every podcast app) `/podcast.xml`.

## `podcast.md`

| Property | Value |
| --- | --- |
| `title` | Required. The show's name, up to 200 characters. |
| `author` | Who makes it. |
| `owner_email` | The address podcast directories may contact. |
| `cover` | The cover image's address: a square JPEG or PNG, 1400 to 3000 pixels, as Apple Podcasts and Spotify ask. |
| `category` | An Apple Podcasts category, such as `Arts` or `Arts > Books`. |
| `explicit` | `true` or `false`. |
| `language` | A code such as `en` or `zh-CN`. |
| `type` | `episodic` (newest first) or `serial` (in order). |
| `copyright` | Up to 300 characters. |
| `apple_url`, `spotify_url` | The show's pages there, shown as listen links. |
| `new_feed_url` | Where the show moved, when it leaves Bearletter. |

The body is the show's description.

## `podcast/<name>.md`

| Property | Value |
| --- | --- |
| `title` | Required. Up to 300 characters. |
| `audio` | Required to publish: the MP3 or M4A file's address in your media library. |
| `duration` | `42:10`, `1:02:15` or a number of seconds. |
| `episode`, `season` | Numbers from 1. |
| `episode_type` | `full`, `trailer` or `bonus`. |
| `explicit` | `true` or `false`. |
| `image` | The episode's own cover. |
| `transcript` | A VTT or SRT file from your media library. |
| `guid` | Kept from another host when the show moved here, so apps do not show episodes twice. |
| `published_date` | `2026-10-02` or `2026-10-02 09:30`, in the blog's time zone. A future date schedules it. |
| `publish` | `false` keeps it a draft. |
| `meta_description` | The summary in apps and search. Without it, the first paragraph is used. |

The body is the show notes.

## Listing episodes on the blog

Put `::podcast` (or `::podcast{limit="5"}`) in `home.md` or a page to list the latest episodes. See [Components](/blog/components).


---

# Text API

Source: https://docs.bearletter.com/api/text-api

The text API reads and writes the same files as the dashboard. Reading and exporting work on every plan; writing is part of Pro.

## Tokens

Create a token in **Settings › Apps & tokens**: **Full access** to read and write, or **Backup (read only)**. It is shown once. Send it with every request:

```http
Authorization: Bearer bl_…
```

**Rotate** gives a token a new secret and ends the old one at once; **Delete** removes it. Keep tokens out of code, logs and shared files.

## Endpoints

All addresses start with `https://api.bearletter.com/v1`.

| Request | Does |
| --- | --- |
| `GET /blogs` | Your blogs: `id`, `subdomain`, `title`. |
| `GET /blogs/{id}/files?kind=post` | Files in the folder; `kind` is `post`, `page` or `file` (site files). |
| `GET /blogs/{id}/file?path=posts/hello.md` | One file with its `content` and `writeSeq`. |
| `PUT /blogs/{id}/file?path=posts/hello.md` | Saves `{ "content": "…", "writeSeq": 3 }`. Use `"writeSeq": null` to create a file. |
| `POST /blogs/{id}/file/move` | Renames `{ "from": "…", "to": "…", "writeSeq": 3 }`. |
| `DELETE /blogs/{id}/file?path=…&writeSeq=3` | Deletes a file. |

`writeSeq` is the version you read. If the file changed since, the save is refused with `409`; read it again and reapply your change.

Saving publishes at once: the blog's pages and feeds refresh within seconds. To keep your own copy of everything, see [Backups](/api/backup).

## Errors

Errors are JSON:

```json
{ "error": { "code": "VALIDATION_ERROR", "message": "Line 3: title: Keep it under 300 characters.", "lines": [{ "line": 3, "message": "title: Keep it under 300 characters." }] } }
```

`lines` points at what to fix in the file. Images in a file must come from your own media library.

## Example

```sh
curl -s https://api.bearletter.com/v1/blogs -H "Authorization: Bearer $BEARLETTER_TOKEN"
```


---

# 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.
