# Merge & combine

> Fold several revisions into one Word document with tracked changes labeled by where they came from.

Two related operations, and picking the right one matters.

**Merge** is for revisions of a shared original: three people each edited `contract.docx`
and you want one document holding all their edits. Each revision is diffed against that
common base, which produces a clean result.

**Combine** is for documents with no shared original: three people each drafted from
scratch. There is no base to diff against, so the engine constructs one by folding the
documents into each other. Prefer merge whenever a shared base exists.

Both produce a single Word document in which every edit is a tracked change labeled by the
version it came from, so each can be accepted or rejected in Word. Both are
order-independent: where revisions conflict, every edit appears as a tracked change
attributed to its source.

## create_merge

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `base_file_path` | string | — | Path to the base document every revision was edited from |
| `base_file_name` | string | — | Display name for the base |
| `next_version_file_paths` | string[] | — | Paths to the revised versions — **at least two** |
| `next_version_file_names` | string[] | — | Display names, in the same order |
| `next_version_authors` | string[] | — | Author label per revision, in the same order. Defaults to the account's author label |
| `merged_file_name` | string | `Merged <base name>` | Name for the result |
| `version_story_name` | string | — | Name for a new project |
| `version_story_id` | string | — | Add to an existing project |

Every revision must be an independent edit of the *same* base. Two or more revisions are
required — with a single revision the base-to-revision redline already is the combined
document, so use [compare](/developers/mcp/compare) instead.

`next_version_authors`, when given, must have exactly as many entries as there are
revisions. It is what makes the result readable: without it every change carries the same
author label and you lose the ability to tell whose edit is whose.

### Response

```json
{
  "status": "awaiting_uploads",
  "version_story_id": "uuid",
  "version_story_name": "Acme MSA",
  "version_story_url": "https://app.versionstory.com/version-story/<id>",
  "upload_manifest_url": "https://... (signed, 1 hour)",
  "uploads": [{ "role": "base", "file_name": "msa.docx", "upload_url": "...", "authorization": "..." }],
  "staged_file_names": ["msa.docx", "msa_legal.docx", "msa_finance.docx"],
  "merge": {
    "merge_version_id": "uuid",
    "merge_mapping_id": "uuid",
    "merged_file_name": "Merged msa.docx",
    "merged_document_url": "https://app.versionstory.com/..."
  }
}
```

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

## get_merged_document

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

Merging generates a comparison of each revision against the base and then folds those
redlines together, so `processing` may come back several times — several minutes is normal.
Call again with identical arguments to keep waiting.

A `processing` response carries `comparison_statuses`, listing each underlying comparison's
file name and generation status, so you can see how far along it is.

### Response — ready

```json
{
  "status": "ready",
  "version_story_id": "uuid",
  "merge": { "merge_version_id": "uuid", "merged_file_name": "Merged msa.docx" },
  "downloads": [{ "option": "merged_docx", "file_name": "Merged msa.docx" }],
  "text_url": "https://... (signed, 1 hour)",
  "text_file_name": "Merged msa.md",
  "download_manifest_url": "https://... (signed, 1 hour)"
}
```

`merged_docx` is the only output format — there is no PDF rendering of a merge. Fetch
`download_manifest_url` for the actual download URL, and save it as binary.

`text_url` is a markdown rendering of the merged document's tracked changes, useful for
analysis. In a merged document, adjacent changes from different revisions competing over
the same text are wrapped in `<conflict id="1">` elements — see
[Reading the changes](/developers/mcp/compare#reading-the-changes).

A `failed` status is terminal and lists causes in `errors`; waiting again does not
regenerate the merge. `awaiting_uploads` lists the untransferred sources in
`missing_uploads`.

## create_combine

Same shape, no base.

| Parameter | Type | Default | Meaning |
| --- | --- | --- | --- |
| `document_file_paths` | string[] | — | Paths to the documents — **at least two** |
| `document_file_names` | string[] | — | Display names, in the same order |
| `document_authors` | string[] | — | Author label per document, in the same order |
| `combined_file_name` | string | `Combined document` | Name for the result |
| `version_story_name` | string | — | Name for a new project |
| `version_story_id` | string | — | Add to an existing project |

The response mirrors merge's, with a `combine` descriptor carrying `combine_version_id` and
`combined_document_url`.

## get_combined_document

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

Identical semantics to `get_merged_document`. The download option is `combined_docx`.