Your team’s documents live on HackMD, and they change constantly. Until now, anything you built on top of HackMD could see a note’s current content and almost nothing about how it got there. If you were writing a release script, auditing documentation drift, or building an agent meant to review a change before it ships, you either reconstructed history by hand or went without it.
The Versions API is now live in production via the HackMD API.
What the Versions API actually is
Five endpoints under /notes/{noteId}/versions. GET on the collection lists version metadata, filtered by named versions only, free-text search, or creator, with pagination. GET with a version reference returns that version’s metadata and content. GET /compare returns a unified diff between two saved versions, or between a saved version and the note’s current content. POST creates a named version. PATCH updates the metadata on one.
A named version is a marker you attach to a snapshot: a name, an optional description, roughly the role a commit message plays. It is not an approval. No sign-off, no permission gate, no verification. Approval workflows are separate work and are not part of this release.
Why we did this
We looked at approval versions first, and user research did not show a strong signal for them. A simpler gap kept surfacing instead: integrations and agents could not see document history at all, so they could not reason about change. History is also the layer approvals would eventually sit on, so building it first was the cheaper order. The commercial reason is real too. We are investing in the developer platform this year, and an interface that only reports the present tense limits what anyone can build on it.
What this means for you
For most people using HackMD, nothing changes today. Version history in the editor behaves exactly as it did, and that is the point: this release adds a programmatic route to something you already had.
If you build integrations, you can tag a publication milestone, diff two releases of a spec, or check whether a doc drifted since the last named version, without scraping the editor.
If you build agents, your agent can read what changed between two states and act on the difference rather than guessing from the latest snapshot.
If you are on a free workspace, content is readable for the 10 most recent versions. Older versions still list, marked content-unavailable. Naming a version is not affected by that limit.
If you use our Model Context Protocol (MCP) server or hackmd-cli, these endpoints are not exposed there yet.
How to try it
You need a HackMD API token and a note ID, the same authentication the rest of the API uses. Start by listing versions, then compare the newest named version against note_content to see what has moved. Version references take one of two forms, note_content or version:{id}, and compare requires both base and target.
One thing to know before you write a client: PATCH acts on the collection path with the target version named in the request body, not on a per-version URL. The reference has the exact shape.
Document history is a foundation, not a feature
Versions is one piece of a longer effort to make HackMD legible to the tools and agents you already use. The Comments API shipped recently on the same reasoning, and named versions will get more company.
Thanks for building on HackMD. Stay tuned for more and don’t hesitate to share your thoughts with us in our Discord. 💜
