---
title: "Get Comparison"
method: GET
path: "/v1/compare/{comparison_id}"
---

# Get Comparison

`GET /v1/compare/{comparison_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/compare/{comparison_id}`
- Auth: HTTP bearer

Return a comparison's redline once it is ready.

Returns the comparison POST /v1/compare started, by comparison_id, its redline as file in each
format asked for: docx (Word tracked changes, the default), pdf, pdf_changed_pages_only, md (its
listing: the text with the changes marked), json, or html; a PowerPoint comparison offers pptx and
pdf, an Excel comparison xlsx. To show the user the redline, ask for pdf; ask for docx only when the user's own
words name Word, .docx or tracked changes, or after they have seen the PDF and ask for it. A
document's type alone is not a reason to. A person sees the PDF, or the html redline where the view
must be interactive; md is for a model to read, and json for code to act on, never to draw the
redline from.
While formats are pending, status is processing: call again with the same arguments until it is
ready. Status failed is terminal for the formats in file.failed_formats, or for the whole
comparison when error is present. Each file.downloads[] entry's url serves the file directly; the
links expire after one hour.

"Compare," "redline" or "diff" by themselves mean produce the file, not explain it.

When the user asks what changed, to explain, summarize or answer a question about the changes, read
the redline's listing: the file.downloads[] entry of format md (ask for format=md), or GET /v1/files/{file_id}?format=md by
file.file_id to search it. Its <ins>, <del>, <moved-from> and <moved-to> elements are the exact
tracked-change set, each naming its revision, and the <revision/> lines at its end list every
revision with its type, author and date; its header says what each tag means.

## Path parameters

- `comparison_id` string, required: The comparison_id POST /v1/compare returned.

## Query parameters

- `format` string[], nullable: docx (default), pdf, pdf_changed_pages_only, md, json, html; 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. pdf_changed_pages_only is the pages that changed, for a quick review. 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. html is the redline to embed in a page where the view must be interactive. PowerPoint comparisons offer pptx (default) and pdf, Excel comparisons xlsx.

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

- ComparisonStatusResponse
  - `comparison_id` string, required
  - `redline_file_id` string, nullable: Deprecated: use file.file_id, the same id. Absent for a presentation or workbook comparison.
  - `status` 'processing' | 'ready' | 'failed', required: The comparison's status; file.status is its redline file's.
  - `downloads` FormatDownload[], nullable: Deprecated: use file.downloads, which serves every format here. Each format here is file's, the same object, md included, except json: here it is the comparison's own json in its older form, while file's json is the redline's listing, which carries the same changes. Each expires_at here keeps its older form, with +00:00 and fractional seconds.
    - `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: Deprecated: use file.pending_formats. The formats of downloads still being made.
  - `failed_formats` string[], nullable: Deprecated: use file.failed_formats. The formats of downloads that will never be made.
  - `error` ComparisonErrorDescriptor
    - `code` string, required
    - `upstream_code` string, nullable
  - `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

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