---
title: "Get Merge"
method: GET
path: "/v1/merge/{merge_id}"
---

# Get Merge

`GET /v1/merge/{merge_id}`

## 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/{merge_id}`
- Auth: HTTP bearer

Return a merged document's download links once it has generated.

Returns the merge POST /v1/merge staged, by merge_id, in each format asked for: docx (the default), pdf, or md (its
tracked changes as text). Merging first compares each revision with the base and then folds those redlines together,
so the call may return status processing several times: calling again with the same merge_id keeps waiting, and
several minutes is normal. A status of failed is terminal. When ready, each file.downloads[] entry carries the url
of one format, a link that serves the file directly: save each file from it, or give it to the user when the client
cannot download files itself. The links expire after one hour.

To read the merge's changes, as when the user asks what changed, read the md entry of file.downloads[].

## Path parameters

- `merge_id` string, required: The merge_id POST /v1/merge returned.

## Query parameters

- `format` string[], nullable: docx (default), pdf, md, json; one or more. pdf is the document to show a person. docx is the Word file with tracked changes, for a lawyer to review and send on. md is the text with the changes marked, for a model to read. json is the same as structured data, for code to act on (counting the changes, routing the document, linking a change to a record). It describes the document's structure and changes, not its layout in pages, so never draw the document from it: show the PDF.

## 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.

## Response `200`

Successful Response

- MergeStatusResponse
  - `merge_id` string, required
  - `status` 'processing' | 'ready' | 'failed', required
  - `file` FileResource: A file: GET /v1/files/{file_id} answers with it, and every response that carries a document embeds it. It never carries version fields: a version holds its file.
    - `file_id` string, required
    - `file_name` string, required
    - `status` 'processing' | 'ready' | 'failed', required: The state of the formats this request asked for: processing while one is still being produced (poll again after Retry-After), ready when every one is in downloads, failed when the document cannot be used (error) or a requested format will never be produced.
    - `downloads` FormatDownload[], nullable: One per requested format that is ready.
      - `format` string, required
      - `url` string, required: Signed; it expires at expires_at.
      - `file_name` string, required
      - `expires_at` string, required: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.
      - `metadata_report` MetadataReport: What a clean found in one download and did to each kind of hidden data.
        - `format` string, required: docx, xlsx, pptx, pdf or zip.
        - `preset` string, required: standard or strict.
        - `items` MetadataReportItem[], required
          - `type` string, required: The kind of hidden data, such as author, tracked_changes or hidden_text.
          - `category` string, required: properties, review, hidden, automation, package or visible.
          - `count` integer, required: How many were found.
          - `action` string, required: What was done: remove, reset, accept, reject, anonymize, convert, unlink, apply, flatten or clean; keep or report when it was left in place.
          - `examples` string[]: A few of the values found, when they are names.
        - `warnings` MetadataReportWarning[], required
          - `type` string, required: The kind of hidden data the warning is about.
          - `message` string, required: What the reader should know before sending the document.
        - `files` integer, nullable: For a zip, how many documents inside it were cleaned.
      - `content_base64` string, nullable: Only in an edit's or a creation's files, with inline=true: the file's bytes, base64-encoded.
    - `pending_formats` string[], nullable: Requested formats still being produced.
    - `failed_formats` string[], nullable: Requested formats that will never be produced.
    - `error` ComparisonErrorDescriptor
      - `code` string, required
      - `upstream_code` string, nullable
  - `error` ComparisonErrorDescriptor
    - `code` string, required
    - `upstream_code` string, nullable

## 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)