Embed redlines

One endpoint returns a comparison's redline as a single, self-contained HTML file: the document with its tracked changes, the script that lays it out in pages and drives navigation, its styles and its images, all inlined. You put that file in a sandboxed iframe on your own page. It renders the redline with the Version Story app's Revisions panel beside the pages: change and comment cards, Filters, and Prev and Next, in a light or a dark theme. Each part of the panel can be turned off, so your page can draw its own instead and drive the document over postMessage.

How it fits together

Your server ──── GET /v1/compare/{id}/html (API key) ────▶ Version Story
     │                                                      returns one HTML file
     ▼
Your page  ── <iframe sandbox="allow-scripts" srcdoc={html}> ── the redline document
     ▲                                                              │
     └──────────────────── postMessage (vs:* messages) ─────────────┘

1. Create a comparison with POST /v1/compare and poll GET /v1/compare/{comparison_id} until its status is ready.
2. On your server, call GET /v1/compare/{comparison_id}/html with your API key and pass embed_origin: the origin of the page that will show the redline. The API key never goes to the browser.
3. Hand the HTML to your page (as JSON, for example) and set it as the srcdoc of an iframe with sandbox="allow-scripts".
4. Optionally, talk to the document: tell it to go to the next change or to a paragraph, and listen for where it is. See Messages.

GET /v1/compare/{comparison_id}/html

Returns the comparison's redline as one self-contained HTML document.

curl -sS "https://api.versionstory.com/v1/compare/cmp_MTp2cy0xOnZtLTE/html?embed_origin=https://app.example.com" \
  -H "Authorization: Bearer vs_live_..." \
  -o redline.html

Query parameters

Booleans accept true/false (or 1/0). The four display parameters set what the document draws when it loads; your page can change any of them afterwards with vs:setOptions. The Revisions panel shows while navigator, sidebar_change_cards or comment_cards is on; with all three off, the pages take the frame's full width.

The panel's theme is not a parameter: the document opens in the light theme, and your page switches it with vs:setOptions (see Themes).

Response — 200 OK

The body is the HTML document (Content-Type: text/html; charset=utf-8), typically a few hundred kilobytes to a few megabytes depending on the document and its images.

What the file contains:

• The redline's text and tracked changes, laid out in pages as in Word.
• The document's script and stylesheet, and the Revisions panel with its styles and fonts, inlined, as Version Story ships them at the time of the request.
• Every image stored with the document, inlined as a data URI. Images the document links from other sites are left out.

The file makes no requests to Version Story. The only external requests it makes are to Google Fonts, for the document's fonts.

Errors

Errors use the standard envelope (see Errors).

The HTML rendering can finish a few seconds after the comparison reports ready. Treat a 409 whose message says the redline is not ready like processing, and retry after a second.

Embedding the document

Put the HTML in an iframe with sandbox="allow-scripts" and set it as srcdoc:

const frame = document.createElement("iframe");
frame.setAttribute("sandbox", "allow-scripts");
frame.title = "Redline";
frame.srcdoc = html; // the body of GET /v1/compare/{comparison_id}/html
container.replaceChildren(frame);

The document runs script built from your customer's file, so sandbox it:

• Use exactly sandbox="allow-scripts". Without allow-same-origin, the document runs with an opaque origin and cannot read your page, its cookies or storage, or navigate it. Never add allow-same-origin to a srcdoc frame: the document would then run with your page's origin.
• Never insert the HTML into your own page's DOM (for example with innerHTML). Keep it in the frame.
• Never serve the HTML as a page of your own site. Send it to the browser as data (JSON or text) and set srcdoc from there.
• Keep the API key on your server. The browser only ever receives the HTML.

Give the frame a height. The document scrolls inside it.

Content Security Policy

The document carries its own Content-Security-Policy, in a <meta> tag at the start of its head. It runs only Version Story's scripts, and blocks every network request except those to Google Fonts.

A srcdoc frame inherits the Content-Security-Policy of the page that embeds it. If your page sends one, it must also allow what the document needs:

script-src 'unsafe-inline';
style-src 'unsafe-inline' https://fonts.googleapis.com;
font-src https://fonts.gstatic.com data:;
img-src data:;

If you cannot loosen your page's policy, serve the HTML from a separate origin dedicated to untrusted content, with its own policy, and frame that URL with the same sandbox instead.

Fetch it when it is viewed

Fetch the HTML each time someone opens the redline rather than storing it. The file carries the version of Version Story's document script that was current when you fetched it; fetching on view means fixes and improvements reach your users on their next view. The response is sent with Cache-Control: no-store for the same reason.

Messages

Your page and the document talk with window.postMessage. Every message is an object with a type starting vs:. Messages are exchanged only when you passed embed_origin and your page, the frame's parent, is at exactly that origin.

Sending. The sandboxed document has an opaque origin, which cannot be named as a target, so send with "*":

frame.contentWindow.postMessage({ type: "vs:next" }, "*");

This is safe because the frame holds the srcdoc you set, and the document accepts messages only from its parent at your embed_origin.

Receiving. A sandboxed frame reports its origin as the string "null", so identify its messages by their source window:

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow) return;
  const message = event.data;
  // message.type is one of the vs:* messages below
});

The text and author names in vs:changes come from your customer's document. Put them in your page as text (textContent), never as HTML.

Messages the document sends

vs:changes

{
  "type": "vs:changes",
  "summary": { "insertions": 9, "deletions": 4, "moves": 0, "comments": 3, "merge_conflicts": 0 },
  "changes": [
    { "anchorId": "28", "kind": "change", "changeType": "insert", "text": "here is a bolded change", "author": "Dana Reyes" },
    { "anchorId": "54d40fe821ef4c13870e2418118ceb12", "kind": "comment", "changeType": "comment", "text": "Here is a comment on v1 NDA", "author": "Corporate Counsel" }
  ]
}

Changes and comments come in document order.

vs:highlighted

{ "type": "vs:highlighted", "anchorId": "31", "index": 1, "total": 9 }

Prev and Next stop at tracked changes, comments, conflicts and footnote references, and skip the kinds that are hidden (see showInsertions, showDeletions, showComments and showMergeConflicts below). Use index and total for a counter such as "2 of 9": ${index + 1} of ${total}.

vs:optionsChanged

{ "type": "vs:optionsChanged", "options": { "showInsertions": false, "showDeletions": true, "showComments": true, "showMergeConflicts": true, "showChangeCards": true } }

Sent when the reader changes a filter in the Revisions panel, with every one of these options as it now is, so your controls can stay in step by taking the message as a whole. Changes your page makes with vs:setOptions are not echoed back.

Messages your page sends

anchorId must be 1 to 128 letters, digits, - or _; other values are ignored. Each move produces a vs:highlighted.

vs:setOptions

frame.contentWindow.postMessage(
  { type: "vs:setOptions", options: { showInsertions: false, theme: "dark" } },
  "*",
);

Every option but theme is a boolean. Each takes effect immediately.

Themes

The Revisions panel, its cards and the space around the pages come in the Version Story app's light and dark themes. The document opens in light; send vs:setOptions with theme: "dark" to switch, before or after vs:ready, for example to follow your page's own theme:

const dark = window.matchMedia("(prefers-color-scheme: dark)");
const setTheme = () =>
  frame.contentWindow.postMessage({ type: "vs:setOptions", options: { theme: dark.matches ? "dark" : "light" } }, "*");
dark.addEventListener("change", setTheme);
frame.addEventListener("load", setTheme);

The pages themselves are the same in both themes: white, with the document's own colors and its tracked changes as Version Story marks them.

Linking to a place in the document

vs:scrollTo accepts any element id the document carries. Two kinds are useful:

• A change or comment: the anchorId of an item in vs:changes.
• A paragraph: the paragraph's id in the comparison's JSON rendering (blocks[].id, from GET /v1/compare/{comparison_id}?format=json). The JSON and the HTML give each paragraph the same id, so a paragraph you found in the JSON can be shown in the document.

The ids of tracked changes inside the JSON rendering (content[].id of an insertion or deletion) are not the document's ids. To link to a single change, use the anchorIds from vs:changes.

Bringing your own navigator

To draw your own change navigator in your page and keep Version Story's cards:

1. Fetch the HTML with navigator=false.
2. Draw Previous and Next buttons that send vs:previous and vs:next.
3. Update a counter from each vs:highlighted.
4. For your own filters, send vs:setOptions with showInsertions or showDeletions.

To list changes in your own sidebar instead of Version Story's cards, also pass sidebar_change_cards=false, comment_cards=false and inline_change_cards=false, build your list from vs:changes, and send vs:scrollTo when an item is clicked.

Example

A complete embedding: a Node server (18 or later, no dependencies) that keeps the API key and fetches the HTML, and a page with its own navigator.

// server.mjs: run with VERSION_STORY_API_KEY=vs_... node server.mjs, then open
// http://localhost:3000/?comparison_id=cmp_...
import http from "node:http";
import { readFile } from "node:fs/promises";

const API = "https://api.versionstory.com";
const ORIGIN = "http://localhost:3000"; // this page's origin, as the browser reports it
const headers = { Authorization: `Bearer ${process.env.VERSION_STORY_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// The redline's HTML, retried while its rendering is still finishing.
async function fetchRedlineHtml(comparisonId) {
  const query = new URLSearchParams({ embed_origin: ORIGIN, navigator: "false" });
  const url = `${API}/v1/compare/${encodeURIComponent(comparisonId)}/html?${query}`;
  for (let attempt = 0; attempt < 30; attempt++) {
    const response = await fetch(url, { headers });
    if (response.ok) return { status: 200, body: { html: await response.text() } };
    const body = await response.json();
    if (response.status !== 409 || !/not ready/i.test(body.error.message)) {
      return { status: response.status, body };
    }
    await sleep(1000);
  }
  return { status: 504, body: { error: { code: "TIMEOUT", message: "The redline did not become ready" } } };
}

http
  .createServer(async (request, response) => {
    const url = new URL(request.url, ORIGIN);
    if (url.pathname === "/") {
      response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
      return response.end(await readFile(new URL("./index.html", import.meta.url)));
    }
    if (url.pathname === "/redline") {
      // Sent as JSON, never as a page of this site: the document's scripts must only run in the sandbox.
      const { status, body } = await fetchRedlineHtml(url.searchParams.get("comparison_id"));
      response.writeHead(status, { "Content-Type": "application/json" });
      return response.end(JSON.stringify(body));
    }
    response.writeHead(404).end();
  })
  .listen(3000);

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <style>
    body { margin: 0; display: flex; flex-direction: column; height: 100vh; font-family: sans-serif; }
    nav { display: flex; gap: 12px; align-items: center; padding: 8px 16px; border-bottom: 1px solid #ddd; }
    iframe { flex: 1; border: 0; }
  </style>
</head>
<body>
  <nav>
    <button id="previous" disabled>Previous</button>
    <span id="position">Loading…</span>
    <button id="next" disabled>Next</button>
    <label><input id="insertions" type="checkbox" checked /> Insertions</label>
    <label><input id="deletions" type="checkbox" checked /> Deletions</label>
    <label><input id="dark" type="checkbox" /> Dark</label>
  </nav>
  <iframe id="redline" title="Redline" sandbox="allow-scripts"></iframe>
  <script>
    const frame = document.getElementById("redline");
    const send = (message) => frame.contentWindow.postMessage(message, "*");

    window.addEventListener("message", (event) => {
      if (event.source !== frame.contentWindow) return;
      const message = event.data;
      if (message.type === "vs:changes") {
        document.getElementById("position").textContent = `${message.summary.insertions + message.summary.deletions} changes`;
      } else if (message.type === "vs:ready") {
        document.getElementById("previous").disabled = false;
        document.getElementById("next").disabled = false;
      } else if (message.type === "vs:optionsChanged") {
        document.getElementById("insertions").checked = message.options.showInsertions;
        document.getElementById("deletions").checked = message.options.showDeletions;
      } else if (message.type === "vs:highlighted") {
        document.getElementById("position").textContent =
          message.index >= 0 ? `${message.index + 1} of ${message.total}` : `– of ${message.total}`;
      }
    });

    document.getElementById("previous").onclick = () => send({ type: "vs:previous" });
    document.getElementById("next").onclick = () => send({ type: "vs:next" });
    document.getElementById("insertions").onchange = (event) =>
      send({ type: "vs:setOptions", options: { showInsertions: event.target.checked } });
    document.getElementById("deletions").onchange = (event) =>
      send({ type: "vs:setOptions", options: { showDeletions: event.target.checked } });
    document.getElementById("dark").onchange = (event) =>
      send({ type: "vs:setOptions", options: { theme: event.target.checked ? "dark" : "light" } });

    const comparisonId = new URLSearchParams(location.search).get("comparison_id");
    fetch(`/redline?comparison_id=${encodeURIComponent(comparisonId)}`)
      .then((response) => response.json())
      .then((body) => {
        if (body.error) throw new Error(`${body.error.code}: ${body.error.message}`);
        frame.srcdoc = body.html;
      })
      .catch((error) => (document.getElementById("position").textContent = error.message));
  </script>
</body>
</html>

Limits

• Only comparisons created with POST /v1/compare of .docx, .doc or .pdf files. Presentation (.pptx) and workbook (.xlsx) comparisons have no HTML rendering.
• The document is laid out in the browser. A long redline with thousands of changes can take several seconds to reach vs:ready.
• Comment cards show each comment with its replies, and mark comments and replies added or deleted between the versions, and comments on text the later version deleted. vs:changes lists replies as separate comments.