# Version history

> Attribute every surviving change across a chain of drafts to the version that introduced it.

Version history — blame, in the engineering sense — answers "who changed what, and when"
across a document's whole life. Given an ordered chain of versions, it produces one Word
document based on the newest version in which **every surviving change is a tracked change
attributed to the version that introduced it**.

Use it when someone wants to know which draft introduced a clause, or whose edit actually
survived to the final document.

## create_version_history

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `version_file_paths` | string[] | — | Paths to the versions — **at least two, ordered oldest first** |
| `version_file_names` | string[] | — | Display names, in the same order |
| `version_authors` | string[] | — | Author label per version, in the same order. Defaults to each version's file name |
| `version_story_name` | string | — | Name for a new project |
| `version_story_id` | string | — | Add to an existing project |

**Order is the whole point.** Versions are passed oldest first, and each is compared to the
one before it, so the ordering determines the attribution. Getting it wrong doesn't error —
it silently produces a wrong answer.

Constraints: at least two versions, all list lengths matching, **file names unique within
the chain**.

### Response

```json
{
  "status": "awaiting_uploads",
  "version_story_id": "uuid",
  "version_story_name": "Acme SOW",
  "version_story_url": "https://app.versionstory.com/version-story/<id>",
  "upload_manifest_url": "https://... (signed, 1 hour)",
  "uploads": [{ "file_name": "sow_v1.docx", "upload_url": "...", "authorization": "..." }],
  "staged_file_names": ["sow_v1.docx", "sow_v2.docx", "sow_v3.docx"],
  "version_history": {
    "version_history_version_id": "uuid",
    "version_history_file_name": "Version history sow_v3.docx"
  }
}
```

Transfer each source with a `PUT` as described in
[Transferring files](/developers/mcp/compare#transferring-files). Generation begins once
the uploads land and the version-to-version comparisons finish.

## get_version_history_document

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `version_story_id` | string | Yes | The project holding the chain |
| `version_history_version_id` | string | Yes | From the create response's `version_history.version_history_version_id` |

Generation produces a comparison between each consecutive pair of versions and then layers
them oldest to newest, so `processing` may come back several times — several minutes is
normal for a long chain. Call again with identical arguments to keep waiting.

### Response — ready

```json
{
  "status": "ready",
  "version_story_id": "uuid",
  "downloads": [
    { "option": "version_history_docx", "file_name": "Version history sow_v3.docx" }
  ],
  "text_url": "https://... (signed, 1 hour)",
  "text_file_name": "Version history sow_v3.md",
  "download_manifest_url": "https://... (signed, 1 hour)"
}
```

`version_history_docx` is the only output format. Fetch `download_manifest_url` for the
download URL and save it as binary.

`text_url` gives you the same attribution as markdown, where each change carries the
`author` and `revision` it came from — see
[Reading the changes](/developers/mcp/compare#reading-the-changes). That is usually the
better input when an agent needs to answer questions about the history rather than hand a
file to a person.

A `failed` status is terminal and lists causes in `errors`. `awaiting_uploads` lists the
untransferred sources in `missing_uploads`.