Keep a shared Markdown document in sync from your app, with an API
Floppy's Docs API is a Markdown document API for apps: your app creates one shared doc with an API key, then sends the whole document as each new version, with a one-line note. Floppy keeps the link, every version, the share page and who read it. Nobody edits the doc on Floppy, so it always matches your app.
fpy.sh/changelog/keep-a-shared-markdown-doc-in-sync-from-your-app · Updated 16 November 2026 · This page as Markdown
What is a managed Markdown doc?
A managed doc is one Markdown link, fpy.sh/<slug>, that another app keeps up to date. Onbrand Review uses it for one live feedback doc per site.
- The app creates the doc once, then pushes each new version of the whole document.
- Floppy keeps every version with its note, the share page, analytics and per-recipient links.
- Nobody edits it on Floppy, the owner included. Upload, restore and Ask to edit point to the app instead.
Viewing, analytics, per-recipient links and the link's settings work as on any other doc. See share a Markdown file as a web page for how the page reads.
How do I create a Markdown doc from my app?
Make an API key, then call POST /api/docs once per doc.
- Open fpy.sh/app/keys, name the key (for example "Onbrand"), choose Read and write and Whole account.
- Send
Authorization: Bearer fpy_live_…with every call. - Call
POST https://fpy.sh/api/docswith{ title, markdown, managed_by: { app, id, url } }.folderis optional: one of your folder ids or names.
The answer is 201 { id, url, version: 1, created: true }. managed_by.id is your own id for the doc, such as a site slug. Calling again with an id this account already has a live doc for returns that doc unchanged, with 200 and created: false. So a retry never makes a second link.
A key acts as its account and reaches only the docs that account made through this API. Each key gets 120 requests a minute.
How do I push a new version of the doc?
Call PUT /api/docs/:id with the whole document and a note.
| Field | What it is |
|---|---|
markdown | The whole new document, not a diff |
note | One line, up to 280 characters, like "ob-12 done in a1b2c3d" |
base_version | Optional: the version you built on. Floppy answers 409 if it isn't the newest |
The answer is { version, status, url }. Floppy checks each version for malware and waits up to about 8 seconds for it. status is live once it passes, scanning while it runs (with version: null for now) and blocked if it fails. A push while the previous one is still being checked gets 409 with retry_after.
Each push renews the link. Its expiry is Never, or a month on the Free plan, counted from the latest push. Readers step through versions as in Markdown version history.
Can a managed doc have images?
Yes. Upload a PNG or WebP image of up to 2 MB with POST /api/docs/:id/assets, as the raw bytes or a multipart form with one file. The answer is 201 { id, url }: put it in the Markdown as .
Other types get 415, and images over 2 MB get 413. Images are served while the doc is on and deleted with it.
What does a reader see on the doc's page?
The page says where the doc comes from: "Live from Onbrand · updated 3 min ago · Open in Onbrand ↗". Under it, a version picker lists every version with its note, like "v13 · ob-12 done in a1b2c3d".
- Copy for your agent sits in the bar where Open in Claude usually is. It copies the Markdown of the version on screen.
- A version the reader hasn't seen is said once, above the text, with Show changes.
- The owner still gets analytics and can make a link for each person: see see who viewed your shared file.
How do I read back the doc, its versions and who opened it?
Three calls, with the same key:
GET /api/docs/:idreturns{ id, url, title, version, updated_at, markdown, managed_by }.GET /api/docs/:id/versionsreturns every version with its note and date, newest first.GET /api/docs/:id/viewsreturns each visit, newest first: a first name when Floppy knows one, the per-recipient link, when they opened it, how long they read, their device, city and country. Bots, scanners and link previews are left out.
Another account's key gets 403 on every :id call, and so does a doc that wasn't made through POST /api/docs.
For AI agents
An agent reads a managed doc like any Markdown link:
GET https://fpy.sh/<slug>withAccept: text/markdown, orhttps://fpy.sh/<slug>?raw=1, returns the current Markdown astext/markdown. This works for any Markdown link, with the same access rules asfpy.sh/<slug>.md.- Over MCP at https://fpy.sh/mcp,
read_doc { link }returns the text as is. Itsnextsays the doc is kept by its app. push_versionandrequest_editanswer403, with anextpointing to the doc's page in its app.
The doc's own text tells the agent how to report fixes back to the app. Floppy doesn't track comment statuses.
Try: "Read fpy.sh/acme, fix the open items in the code, then report each one back the way the doc says."
Questions people ask
Can I edit a managed doc on Floppy?
No. A managed doc is kept by its app, so upload, restore and Ask to edit are gone for everyone, the owner included. Make the change in the app, and it pushes the next version.
What happens if two pushes of a managed doc happen at once?
Floppy checks one version at a time. A push while the previous one is still being checked gets 409 with retry_after. Send base_version too, and a push built on an older version gets 409 instead of overwriting the newer one.
Does creating the same managed doc twice make two links?
No. POST /api/docs is idempotent per managed_by.id: if this account already has a live doc for that id, Floppy returns it unchanged with 200 and created: false.
Can an app on Cloudflare skip the API key?
Yes. A Worker on the same Cloudflare account can call Floppy's DocsApi through a service binding, with the same calls: createDoc, pushVersion, readDoc, versions, views and addAsset.
How does an AI agent read a managed Markdown doc?
It asks fpy.sh/<slug> for text/markdown, or adds ?raw=1, and gets the current Markdown as plain text. Over MCP, read_doc returns it as is, and the share page's Copy for your agent copies it.
What shipped in v1.45.0
- The Docs API: an app like Onbrand Review makes one Markdown doc with an API key, then sends each new version with a note
- Its page says where it's from and when it last changed, has a version picker with each note, and Copy for your agent
- Nobody edits it on Floppy, the owner included: the page, push_version and request_edit point to the app instead
- Any Markdown link reads as plain text from the link itself: ask fpy.sh/<slug> for text/markdown, or add ?raw=1