---
title: "Create Merge"
method: POST
path: "/v1/merge"
---

# Create Merge

`POST /v1/merge`

## Request

- Base URL: `https://api.versionstory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.versionstory.com/v1/merge`
- Auth: HTTP bearer

Merge two or more revised copies of one base document into a single Word document.

Use this when several people have separately edited the same original document and the user wants one combined
draft. The result carries each revision's edits as tracked changes, labeled by the revision they came from, so each
edit can be accepted or rejected in Word. Each revision is diffed against the same base, so the result does not depend
on their order: where revisions conflict, every edit appears as a tracked change attributed to its revision.
Give each revision its author, the name its tracked changes are credited to. Propose the attribution from what is
visible (document properties when readable, file names, the documents' own text), confirm it with the user, and ask
when nothing gives a basis for a proposal. When the user's words or the file names
make the base clear, proceed with it and say which document was used as the base; ask which draft the others started
from, in the user's own terms, only when it is genuinely unclear. Never ask about merge order.

The merged document opens with a cover sheet on reviewing it and ends with a summary of each revision's changes;
leave either out with include_cover_sheet or include_changes_summary false, as when the merged document replaces the
user's own copy. Excel files are not supported.

Send a JSON body naming documents already in Version Story: original, and revisions, at least two, each a file
{"file_id"} (upload a local file with POST /v1/files first) or a Document's version {"document_id", "version_id"}, and
each revision with its author. The multipart/form-data upload of the documents' bytes (original, revisions and
revision_authors fields) is deprecated: use the JSON body. The call answers at once with the merge_id
GET /v1/merge/{merge_id} serves the merged document by.

## Headers

- `X-Customer-Id` string, nullable: Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide.

## Request body

- MergeRequest: POST /v1/merge's JSON body: documents already in Version Story, each revision with its author.
  - `original` MergeDocument, required: A document already in Version Story that a merge reads: a file by its file_id, or a Document's version by its document_id and version_id (a version reference sent back as it is, its index and label ignored).
    - `file_id` string, nullable: A file you uploaded (POST /v1/files) or an edit's files.clean.
    - `document_id` string, nullable: With version_id: the Document holding the version (GET /v1/documents/{document_id}).
    - `version_id` string, nullable: With document_id: the version, or "latest" for the newest.
    - `index` integer, nullable: Ignored.
    - `label` string, nullable: Ignored.
  - `revisions` MergeRevision[], required: Two to 10 revised copies of the base document.
    - `file_id` string, nullable: A file you uploaded (POST /v1/files) or an edit's files.clean.
    - `document_id` string, nullable: With version_id: the Document holding the version (GET /v1/documents/{document_id}).
    - `version_id` string, nullable: With document_id: the version, or "latest" for the newest.
    - `index` integer, nullable: Ignored.
    - `label` string, nullable: Ignored.
    - `author` string, nullable: The name this revision's tracked changes are credited to. Defaults to the user's name, or for an API key the revision's file name.
  - `include_cover_sheet` boolean: Whether the merged document opens with the cover sheet explaining how to review it.
  - `include_changes_summary` boolean: Whether the merged document ends with the summary of each revision's changes.

## Response `202`

Successful Response

- MergeAcceptedResponse
  - `merge_id` string, required: The merge's id (mrg_...), which GET /v1/merge/{merge_id} takes.
  - `status` 'processing', required

## Other responses

- `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal.

---

[API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)