# BotCanvas

> BotCanvas is a big-screen board for your user. You push text, pictures, links and charts to it, and they show up full screen in their browser (for example in their car).

## Your board key
- If you don't have one yet, create a board: `POST https://botcanvas.us/api/signup`. You get back a `key`. It is shown only once, so keep it somewhere safe.
- Send it on every call as `Authorization: Bearer <key>`. Never put it in a link or say it aloud.

## Getting paired
1. Ask for a pairing code: `POST https://botcanvas.us/api/pin` with your board key. You get a pairing code of 6 letters and numbers (like K7M2QX) that works once, for 5 minutes.
2. Tell your user: "Open botcanvas.us and type K7M2QX." Spell it out clearly if you are speaking. Capitals, spaces and dashes don't matter when they type it.
3. When they type it, their screen is paired with their board for 30 days. If it ever un-pairs, ask for a new code and tell them again.
4. Already have the board open? Tap Add another screen to get a code for a second display. (Your user can do this on a paired screen without asking you; it doesn't cancel your own code.)

## Pushing to the board
`POST https://botcanvas.us/api/push` with one of:
- `{"type":"text", "title":"...", "body":"...", "source":"..."}` (body may use simple markdown: **bold**, *italic*, `code`, - lists, [links](https://...))
- `{"type":"image", "title":"...", "url":"https://...", "source":"..."}` (or a small picture as `data:image/png;base64,...`, under about 170 KB)
- `{"type":"link", "title":"...", "url":"https://...", "source":"..."}`
- `{"type":"chart", "title":"...", "data":[1,3,2,5], "source":"..."}`

`source` is a short name for you (up to 24 characters) shown on the board as "<source> · <age>". Keep each push under 1 MB (pictures up to about 1 MB; the board holds up to 20 items). You get back an `id`, plus `viewers` (how many screens have the board open right now) and a `note` you can pass on.

## Is anyone watching?
`GET /api/status` tells you `viewers` and how many items the board holds. If nobody is watching, the push shows up when your user opens the board if it is still kept. If it doesn't show up, push again after they open it.

## Other things you can do
- See what is on the board: `GET /api/items`
- See whether anyone is watching: `GET /api/status`
- Choose how long items are kept, and whether to keep them when the board is closed: `POST /api/settings`
- Remove one item: `DELETE /api/item/{id}`
- Clear the board: `POST /api/clear`
- See what your user drew on the board with the red pen: `GET /api/markup?since=<ms>`. Each entry has a `pngUrl` you can download with your board key, plus the title and source of the item they drew on.

## How the board behaves
The newest item shows full screen after a 5-second countdown. Your user can pause, or step back through the last 10 screens.

## How long things last
By default, items are kept in memory only, never written to disk. While your board is open in a browser, items stay for the time you choose (default 30 minutes). When nobody has the board open, keeping them is best effort: the service may clear an idle board early, sometimes within minutes, and the longer the setting, the more likely that is. If something is missing, ask your bot to send it again.

There are two modes:
- Memory only (default): items are never written to disk. They're reliable while your board is open; when nobody is watching, the service may clear them early, so keep the board open to receive updates.
- Keep when closed (optional): items are saved to disk temporarily and deleted automatically when your chosen time runs out (5 minutes to 24 hours), so they're there when you come back. Turning this off or clearing the board deletes them right away.

Choose with `POST /api/settings` and `{"keep_minutes": 60, "disk": true}` (keep_minutes 5 to 1440; disk true or false). You can also add `keep_minutes` to any push. If the service restarts, settings go back to the default (30 minutes, memory only) until you send them again. These settings are yours to choose: the board page has no controls for them, it only shows how long items are kept. Every push answer tells you `keep_minutes` and `mode` (`memory` or `disk`).

When your user opens the board, they get everything currently kept. Check `viewers` in the push answer: if it is 0, nobody is watching yet, so push again after your user opens the board if needed.

## If something goes wrong
Every error comes back as `{"error": "..."}` in plain words you can repeat to your user, for example "That code has expired. Ask your bot for a new one."

## Example
```
curl -X POST https://botcanvas.us/api/push -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"type":"text","title":"Hi","body":"Hello from my bot","source":"My Bot"}'
```

## More detail
- Full list of calls: https://botcanvas.us/openapi.json
- Tool address for assistant apps: https://botcanvas.us/connect