Versioning in most CMSs is an afterthought \u2014 a history log you rarely use and even more rarely automate. EmDash flips that completely. Its Revisions API was built for programmatic control, not just audit trails. Most developers overlook this power, treating revisions as a safety net rather than a foundation for workflows. By the end of this guide, you’ll see revisions as a programmable layer that can power custom approval chains, content scheduling, and collaborative editing \u2014 not just a place to undo mistakes.<\/p>\n
WordPress stores revisions as serialized post meta, tightly coupled to the editor. EmDash treats revisions as first-class data objects. Every content type \u2014 posts, pages, custom types \u2014 automatically generates revision records on each save. But the API exposes far more than a simple list of past versions.<\/p>\n
The Revisions API gives you:<\/p>\n
These capabilities let you build versioning systems that WordPress could never support natively.<\/p>\n
Out-of-the-box versioning solves \u201coops, I need to undo that.\u201d Custom versioning solves real business problems:<\/p>\n
EmDash’s API makes each of these possible in under 200 lines of code.<\/p>\n
Before you start, you need:<\/p>\n
content:write<\/code>codecodecode and content:read<\/code>codecodecode permissions<\/li>\n- Node.js 18+ or a runtime that supports fetch<\/li>\n<\/ul>\n
Generate your token in EmDash admin under Settings \u2192 API Tokens. Scope it to only what your custom versioning system needs.<\/p>\n
Step 1: Understanding the Revision Data Structure<\/h2>\n
Every content revision in EmDash is stored as a JSON object with this shape:<\/p>\n
“`json<\/p>\n
{<\/p>\n
“id”: “rev_abc123”,<\/p>\n
“documentId”: “doc_xyz789”,<\/p>\n
“version”: 5,<\/p>\n
“data”: { … },<\/p>\n
“diff”: { … },<\/p>\n
“author”: { “id”: “user_1”, “name”: “Jane” },<\/p>\n
“createdAt”: “2026-04-10T14:23:00Z”,<\/p>\n
“metadata”: { “reason”: “Updated pricing section” }<\/p>\n
}<\/p>\n
“`<\/p>\n
The data<\/code>codecodecode field contains the full content snapshot at that revision. The diff<\/code>codecodecode field holds a structured diff (added, removed, changed paths). metadata<\/code>codecodecode is a free-form object you can populate when creating a revision programmatically.<\/p>\nExpected outcome:<\/strong> You understand exactly what the API returns and can map it to your own data structures.<\/p>\nStep 2: Fetching Revisions for a Document<\/h2>\n
To get all revisions for a specific piece of content, use the endpoint:<\/p>\n
“`<\/p>\n
GET \/api\/revisions?documentId=doc_xyz789&limit=50<\/p>\n
“`<\/p>\n
The response is paginated. Include cursor<\/code>codecodecode for the next page.<\/p>\n“`javascript<\/p>\n
async function getRevisions(documentId, limit = 50) {<\/p>\n
const res = await fetch(https:\/\/your-site.com\/api\/revisions?documentId=${documentId}&limit=${limit}<\/code>codecodecode, {<\/p>\n headers: { Authorization: Bearer ${API_TOKEN}<\/code>codecodecode }<\/p>\n });<\/p>\n
return res.json();<\/p>\n
}<\/p>\n
“`<\/p>\n
You can filter by author, date range, or status change. For example, to find all revisions where the status changed to “published”:<\/p>\n
“`<\/p>\n
GET \/api\/revisions?documentId=doc_xyz789&statusChange=published<\/p>\n
“`<\/p>\n
Expected outcome:<\/strong> You can retrieve any revision set and filter programmatically.<\/p>\nStep 3: Creating a Custom Diff Viewer<\/h2>\n
The built-in EmDash admin shows a basic diff. But you can build a richer comparison using the diff<\/code>codecodecode field. The diff is stored as a JSON patch (RFC 6902). Here’s a minimal renderer:<\/p>\n“`javascript<\/p>\n
function renderDiff(diff) {<\/p>\n
return diff.map(op => {<\/p>\n
if (op.op === ‘replace’) {<\/p>\n
return <\/p>\n${op.path}: ${op.value}<\/div>\n<\/code>codecodecode;<\/p>\n
}<\/p>\n
if (op.op === ‘add’) {<\/p>\n
return <\/p>\n+ ${op.path}: ${op.value}<\/div>\n<\/code>codecodecode;<\/p>\n
}<\/p>\n
if (op.op === ‘remove’) {<\/p>\n
return <\/p>\n- ${op.path}<\/div>\n<\/code>codecodecode;<\/p>\n
}<\/p>\n
return ”;<\/p>\n
}).join(‘n’);<\/p>\n
}<\/p>\n
“`<\/p>\n
This gives you a side-by-side or inline diff that you can embed in a custom editorial dashboard, a Slack webhook, or an email notification.<\/p>\n
Expected outcome:<\/strong> A reusable diff component that works outside the admin panel.<\/p>\nStep 4: Implementing Programmatic Rollback<\/h2>\n
Rolling back to a previous revision is a single API call:<\/p>\n
“`<\/p>\n
POST \/api\/documents\/doc_xyz789\/rollback<\/p>\n
Body: { “revisionId”: “rev_abc123” }<\/p>\n
“`<\/p>\n
But you should add safeguards. Here’s a safe rollback function that checks permissions and logs the action:<\/p>\n
“`javascript<\/p>\n
async function rollbackToRevision(documentId, revisionId, reason) {<\/p>\n
\/\/ Validate the revision exists<\/p>\n
const rev = await getRevision(revisionId);<\/p>\n
if (!rev) throw new Error(‘Revision not found’);<\/p>\n
\/\/ Execute rollback<\/p>\n
const res = await fetch(https:\/\/your-site.com\/api\/documents\/${documentId}\/rollback<\/code>codecodecode, {<\/p>\n method: ‘POST’,<\/p>\n
headers: {<\/p>\n
Authorization: Bearer ${API_TOKEN}<\/code>codecodecode,<\/p>\n ‘Content-Type’: ‘application\/json’<\/p>\n
},<\/p>\n
body: JSON.stringify({<\/p>\n
revisionId,<\/p>\n
metadata: { reason, rolledBackBy: currentUser }<\/p>\n
})<\/p>\n
});<\/p>\n
if (!res.ok) throw new Error(‘Rollback failed’);<\/p>\n
\/\/ The rollback itself creates a new revision, so you can audit it<\/p>\n
return res.json();<\/p>\n
}<\/p>\n
“`<\/p>\n
Expected outcome:<\/strong> A production-ready rollback function that leaves an audit trail.<\/p>\nStep 5: Automating Revision Pruning<\/h2>\n
Revisions accumulate. EmDash doesn’t auto-delete old ones (yet). Build a cleanup worker that runs daily:<\/p>\n
“`javascript<\/p>\n
\/\/ Cloudflare Worker cron trigger: 0 0 <\/em> *<\/p>\nasync function pruneRevisions(env) {<\/p>\n
const thirtyDaysAgo = Date.now() – 30 24 <\/em> 60 60 <\/em> 1000;<\/p>\n \/\/ Fetch all documents, then for each, delete revisions older than 30 days<\/a><\/p>\n const docs = await fetch(‘https:\/\/your-site.com\/api\/documents’, {<\/p>\n
headers: { Authorization: Bearer ${env.API_TOKEN}<\/code>codecodecode }<\/p>\n }).then(r => r.json());<\/p>\n
for (const doc of docs) {<\/p>\n
const revisions = await getRevisions(doc.id);<\/p>\n
const oldRevisions = revisions.filter(r => new Date(r.createdAt) < thirtyDaysAgo);<\/p>\n
for (const rev of oldRevisions) {<\/p>\n
await fetch(https:\/\/your-site.com\/api\/revisions\/${rev.id}<\/code>codecodecode, {<\/p>\n method: ‘DELETE’,<\/p>\n
headers: { Authorization: Bearer ${env.API_TOKEN}<\/code>codecodecode }<\/p>\n });<\/p>\n
}<\/p>\n
}<\/p>\n
}<\/p>\n
“`<\/p>\n
Expected outcome:<\/strong> Automated cleanup that prevents database bloat without losing<\/a> recent history.<\/p>\nComparison: Versioning Strategies<\/h2>\n
\n\n\nApproach<\/th>\n Storage<\/th>\n Rollback Speed<\/th>\n Audit Trail<\/th>\n External Access<\/th>\n AI-Friendly<\/th>\n<\/tr>\n<\/thead>\n \n\nEmDash Revisions API<\/strong><\/td>\nJSON in D1\/SQLite<\/td>\n Instant (single API call)<\/td>\n Full metadata, author, reason<\/td>\n Yes, via API<\/td>\n Yes (MCP server reads diff)<\/td>\n<\/tr>\n \nGit-based versioning<\/strong><\/td>\nGit repository<\/td>\n Minutes (clone + checkout)<\/td>\n Commit messages only<\/td>\n Requires git access<\/td>\n Limited (no structured diff)<\/td>\n<\/tr>\n \nManual database snapshots<\/strong><\/td>\nSQL dump<\/td>\n Hours (restore entire DB)<\/td>\n None unless logged<\/td>\n No<\/td>\n No<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nThe EmDash approach wins for speed, granularity, and programmability.<\/p>\n
Advanced: Connecting Revisions to AI Agents<\/h2>\n
EmDash ships with a built-in MCP server. You can expose your custom versioning system as a tool. For example, an agent can:<\/p>\n
\n- “Roll back the homepage to the version from last Tuesday”<\/li>\n
- “Show me all revisions where Jane made changes to the pricing table”<\/li>\n
- “Create a new revision of the about page with these updated team photos”<\/li>\n<\/ul>\n
The agent reads the revision data through MCP and performs actions via the API. This turns your versioning system into an automated editorial assistant.<\/p>\n
When the General Advice Fails<\/h2>\n
Custom versioning works well for structured content \u2014 blog posts, pages, product descriptions. It breaks down for highly dynamic content like real-time collaborative documents or user-generated content streams. In those cases, the revision API’s snapshot model creates too much overhead. You’d be better off with operational transforms (OT) or CRDTs. But for 90% of content management use cases, EmDash’s Revisions API is the right foundation.<\/p>\n