BearletterDocsllms.txtbearletter.comDashboard

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.

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:

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.

RequestDoes
GET /blogsYour blogs: id, subdomain, title.
GET /blogs/{id}/files?kind=postFiles in the folder; kind is post, page or file (site files).
GET /blogs/{id}/file?path=posts/hello.mdOne file with its content and writeSeq.
PUT /blogs/{id}/file?path=posts/hello.mdSaves { "content": "…", "writeSeq": 3 }. Use "writeSeq": null to create a file.
POST /blogs/{id}/file/moveRenames { "from": "…", "to": "…", "writeSeq": 3 }.
DELETE /blogs/{id}/file?path=…&writeSeq=3Deletes 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.

Errors#

Errors are 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#

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

Bearletter · bearletter.com · Every page is also Markdown: llms.txt