# 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"
```
