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