Quickstart

Version Story exposes its comparison engine two ways. Pick the one that matches how your code works — you don't need both.

Redline two documents over REST

You need an API key. Create one in the Version Story web app under Settings → Developer — see Authentication for what the key is and how to handle it. API access is switched on per organization by the Version Story team, so if you don't see a Developer section in Settings, schedule a demo and we'll enable it for you.

1. Submit the two documents. original is the earlier version, modified is the revised one. The response comes back immediately with 202 Accepted; nothing is generated yet.

curl -sS https://api.versionstory.com/v1/compare \
  -H "Authorization: Bearer vs_live_..." \
  -F "original=@nda_v1.docx" \
  -F "modified=@nda_v2.docx" \
  -F "author=Dana Reyes"

{ "comparison_id": "cmp_MTp2cy0xOnZtLTE", "status": "processing" }

author is optional and sets who the tracked changes are attributed to in Word.

2. Poll until it's ready. The same request repeated. While generation is underway the response carries Retry-After: 1, so wait a second between attempts.

curl -sS https://api.versionstory.com/v1/compare/cmp_MTp2cy0xOnZtLTE \
  -H "Authorization: Bearer vs_live_..."

{
  "comparison_id": "cmp_MTp2cy0xOnZtLTE",
  "status": "ready",
  "downloads": [
    {
      "format": "docx",
      "url": "https://documents.versionstory.com/...",
      "file_name": "Redline nda_v1 to nda_v2.docx",
      "expires_at": "2026-08-10T22:00:00+00:00"
    }
  ]
}

3. Download the redline. The URL is signed and valid for one hour. Polling again mints a fresh one, so an expired link is never a dead end.

curl -sS --fail -o redline.docx "<downloads[0].url>"

That gives you a Word document with real tracked changes. format is repeatable and accepts a comma-separated list, so ?format=docx,md returns the Word file and a Markdown rendering in one call; pdf and pdf_changed_pages_only are the other options. Formats that are ready come back immediately, with any still generating named in pending_formats. The full reference is on REST · Compare.

To reconcile several people's edits to the same document rather than compare two versions, use REST · Merge.

The whole loop, in Python

import time
import requests

BASE = "https://api.versionstory.com"
headers = {"Authorization": "Bearer vs_live_..."}

with open("nda_v1.docx", "rb") as original, open("nda_v2.docx", "rb") as modified:
    created = requests.post(
        f"{BASE}/v1/compare",
        headers=headers,
        files={"original": original, "modified": modified},
        data={"author": "Dana Reyes"},
    )
created.raise_for_status()
comparison_id = created.json()["comparison_id"]

while True:
    status = requests.get(f"{BASE}/v1/compare/{comparison_id}", headers=headers)
    status.raise_for_status()
    body = status.json()
    if body["status"] == "ready":
        break
    if body["status"] == "failed":
        raise RuntimeError(f"Comparison failed: {body['error']['code']}")
    time.sleep(int(status.headers.get("Retry-After", 1)))

download = body["downloads"][0]
redline = requests.get(download["url"])
redline.raise_for_status()
with open(download["file_name"], "wb") as out:
    out.write(redline.content)

Redline documents over MCP

No key here — add the connector to any MCP client and sign in with your Version Story account.

https://mcp-compare.versionstory.com/mcp

The client discovers the tools itself, registers as an OAuth client, and opens a sign-in page. For step-by-step setup in Claude, see the Claude installation guide — or, on the Claude desktop app and in Cowork, install the Version Story plugin instead.

Once connected, the agent stages a comparison, transfers the source files, and waits for the redline:

1. create_comparison — stages the work and returns upload targets
2. An HTTP PUT per source file, using the manifest's upload_url and authorization
3. get_redlines — blocks server-side until the redline exists, then returns a download manifest

Full parameter and response reference on MCP · Compare. Merge, combine, and version history follow the same stage-transfer-wait-download shape.

Next steps

• Authentication — API keys and OAuth in detail
• Formats & limits — file types, size caps, expiry
• Errors — every error code and what to do about it