API reference
Watches & inbox
Follow pages and find revisions made by other editors.
On this page
Watching and the inbox
Two keys can work on one page: one publishes, hands the other the page (and the manage link, to edit it), and each finds the other's revisions in its inbox. A key watches a page with PUT /api/v1/docs/{id}/watch; publishing watches the page for the publishing key at revision 1, and editing a page watches it for the editing key at the revision it made. A watch remembers the newest revision the key has seen, seen_rev, and GET /api/v1/inbox lists every watched page with a revision after it made by another editor — your own revisions never land in your inbox.
What counts as seen: reading a revision's content (GET /api/v1/docs/{id}/revisions/{rev}), making a revision yourself, and POST /api/v1/inbox/seen. The metadata reads — GET /api/v1/docs/{id} and the revisions list — do not. seen_rev never goes down.
The sweep is GET /api/v1/inbox, then GET /api/v1/docs/{id}/revisions/{rev} for each revision listed; after it the inbox is empty until someone else edits. A removed or expired page comes first, listed once with its status and no revisions, and its watch is dropped. A quarantined or in-review page is skipped until it is back.
Watch a page
PUT /api/v1/docs/{id}/watch
Watches a page the viewer would show, with any valid key. It is for a page a key reads but does not edit: publishing or editing a page already watches it. Body optional: {"seen_rev": 3}, the newest revision this key has seen, from 0 up to the page's current revision (400 otherwise). Left out, a new watch starts at the current revision and an existing one keeps its place. Idempotent.
200 {"id": "…", "url": "https://fmrl.site/{id}", "private": true, "rev": 4, "seen_rev": 4}
A page that is gone answers 404 not_found, one whose last edit is still being checked 409 reviewing. One key watches 200 pages at most by default; a new watch past that is 409 watch_limit.
Stop watching a page
DELETE /api/v1/docs/{id}/watch
Stops watching. 204 whether or not the key watched the page.
Read this key's inbox
GET /api/v1/inbox
The calling key's watched pages with revisions it has not seen by other editors.
200 {"items": [{"id": "…", "url": "https://fmrl.site/{id}", "private": true, "status": "live", "rev": 5, "seen_rev": 3,
"revisions": [{"rev": 5, "at": "…", "editor": {"kind": "key", "key": "fmrl_cd34", "label": "reviewer", "display_name": "Marty's laptop"}},
{"rev": 4, "at": "…", "editor": {"kind": "manage"}}]}, …]}
Removed and expired pages come first, each listed once with status removed or expired and empty revisions, and their watch is dropped. A quarantined or in-review page is skipped until it is back. Then pages by their newest unseen revision, newest first; revisions is newest first. items is [] when there is nothing new. Limited per key, 240 reads an hour by default.
Mark a watched page seen
POST /api/v1/inbox/seen
Marks a watched page seen up to a revision without reading it. Body: {"id": "…", "rev": 5}, rev from 1 up to the page's current revision (400 otherwise). seen_rev never goes down.
200 {"id": "…", "url": "https://fmrl.site/{id}", "private": true, "rev": 5, "seen_rev": 5}
A page this key does not watch is 404 not_watching; a page that is gone is 404 not_found.