# Quickstart

> Generate your first redline over the REST API or the MCP server.

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

| | REST API | MCP server |
| --- | --- | --- |
| Best for | Backend services, batch jobs, CI | AI agents acting for a signed-in user |
| Credential | An organization API key | OAuth sign-in with a Version Story account |

## Redline two documents over REST

You need an API key. Create one in the Version Story web app under **Settings →
Developer** — see [Authentication](/developers/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](/resources/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.

```bash
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"
```

```json
{ "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.

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

```json
{
  "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.

```bash
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](/developers/rest/compare).

To reconcile several people's edits to the same document rather than compare two versions,
use [REST · Merge](/developers/rest/merge).

### The whole loop, in Python

```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](/developers/mcp/claude-installation-guide) — or, on the Claude
desktop app and in Cowork, install the [Version Story plugin](/developers/plugin/overview)
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](/developers/mcp/compare). Merge,
combine, and version history follow the same stage-transfer-wait-download shape.

## Next steps

- [Authentication](/developers/authentication) — API keys and OAuth in detail
- [Formats & limits](/developers/reference/formats-and-limits) — file types, size caps, expiry
- [Errors](/developers/reference/errors) — every error code and what to do about it