# PostFrog API: overview

PostFrog is a Telegram bot that helps channel authors make posts. Through this API (and the MCP server on top of it) an agent sends **materials**, and PostFrog turns each one into a **post draft** for the author who owns the API key.

## Where the posts go

- Posts are **not returned to you** as the result of a call. Each post arrives as a draft in the author's private chat with the PostFrog bot, as a normal message with a preview and buttons.
- Drafts arrive **in the order of your batch**. If the author is chatting with the bot right now, finished posts wait for about 2 minutes of silence so they do not break the conversation.
- After delivery the draft is an ordinary PostFrog post: the author edits it in free text ("make it shorter", "add a button"), changes media and buttons, and **publishes it to their channel with one tap**.
- You can read the final text of each post with `get_batch` (field `post.text`, same markup as the input of `exact`).

## What you cannot do

- Publish to a channel, schedule a post or edit a published one. Only the author does that, in the bot.
- Send anything to other people. The bot writes only to the owner of the key.
- Use the API on Free or on the Pro trial: a **paid** Pro plan is required (HTTP 403 `pro_required` otherwise).

## Workflow

1. `get_account` - plan, posts left, today's quota, the author's default format and language, all limits.
2. (media from a local file) `create_upload`, then upload the file with the `curl` command it returns.
3. `validate_post` - for `exact` posts: a free dry run of the same checks `send_posts` runs. Nothing is saved.
4. `send_posts` - one batch of 1 to 10 items. The response has `batch_id` and one `item_id` per item with status `queued`.
5. `get_batch` - statuses, `warnings`, errors and the final post text. Poll it no more than a few times a minute; generation of one item takes from seconds (`exact`) to a minute or two (`write` with links and media). Items may also wait in the queue (other items of the author, the author chatting with the bot). You do not have to wait for delivery: once `send_posts` succeeded, it is fine to tell the user the drafts will arrive in their PostFrog chat and stop.
6. `cancel_batch` - cancels items that have not started yet.

## Tools and REST endpoints

| MCP tool | REST | What |
|---|---|---|
| `get_account` | `GET https://bot.postfrog.site/api/v1/me` | account, quotas, limits |
| `get_guide` | `GET https://bot.postfrog.site/api/v1/guide?topic=` | this guide |
| `validate_post` | `POST https://bot.postfrog.site/api/v1/validate` | check an `exact` post |
| `create_upload` | `POST https://bot.postfrog.site/api/v1/uploads` (multipart) | upload a photo or video file |
| `send_posts` | `POST https://bot.postfrog.site/api/v1/batches` (+ `Idempotency-Key` header) | send a batch |
| `get_batch` | `GET https://bot.postfrog.site/api/v1/batches/{id}` | batch status and results |
| `cancel_batch` | `DELETE https://bot.postfrog.site/api/v1/batches/{id}` | cancel queued items |

MCP server: `https://bot.postfrog.site/mcp` (Streamable HTTP). Every request carries `Authorization: Bearer pf_live_…` - the author's key from the bot (Settings, "API & MCP"). Never print or log the key.

## Guide topics

- `modes` - `exact`, `format`, `write`: which one to pick. **If you can write, write the post yourself and send `exact`.**
- `formatting` - PostFrog Rich Markdown (the markup of `exact` posts and of the results), Markdown mode, a cheat sheet.
- `buttons` - link and copy buttons: the `buttons` field and `<tg-button>` tags.
- `media` - photos and videos: URLs, uploads, placement, warnings.
- `limits` - quotas, statuses, error codes and what to do on each.
- `examples` - complete requests from task to JSON.