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 → Organization → API Keys — see Authentication for what the key is and how to handle it.

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"

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

2. Poll until it's ready. The same request repeated. While generation is underway the response carries Retry-After: 5, so wait five seconds 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},
    )
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", 5)))

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 Claude Connector Setup.

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