--- title: "Create Comparison" method: POST path: "/v1/compare" --- # Create Comparison `POST /v1/compare` ## 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` - Auth: HTTP bearer Compare, diff, or redline documents into a true redline: Word tracked changes, a PDF, or a PDF of the changed pages only. original is the base (earlier) document and modified the revised (later) one. Word, PDF, DOC and email (.eml/.msg) documents compare with each other; an Excel workbook compares with another workbook and a PowerPoint presentation with another presentation. Compare the files the user gives as given: pass them even when a Document of that name holds versions, and never hand over a stored redline in their place, since the user's file may have changed since. Send both documents' bytes as multipart/form-data, in the original and modified fields. The call answers at once with the comparison_id GET /v1/compare/{comparison_id} serves the redline 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 `multipart/form-data` - BodyCreateComparisonV1ComparePost - `original` string, binary, required: The base (earlier) document - `modified` string, binary, required: The revised (later) document - `author` string, nullable: Name to attribute the redline's tracked changes to. Defaults to the revised document's file name. - `preserve_track_changes` boolean: Keep the tracked changes already in both documents as they are, each under its own author, and add as new tracked changes, under author, only the real differences: original against modified with modified's own tracked changes rejected. For a counterparty's draft that carries their tracked changes: send it as original, and your copy of it, edited with or without Track Changes, as modified. Word documents only; refused for presentations and workbooks. Default false, which compares the documents as if every tracked change in both were accepted. - `show_formatting_changes` boolean: Track formatting changes (font, size, bold, color, alignment, spacing, table layout) in the redline. Not applied with preserve_track_changes or to a document converted from a PDF. Word documents only. Default false. - `track_redline_changes` boolean: When an uploaded PDF is a redline (insertions underlined in one color, deletions struck through in another), turn its insertions and deletions into tracked changes in the Word document made from it. Default true. A PDF that is not a redline, and any other kind of document, is unaffected. Applies to the documents this request uploads; a document already in Version Story keeps the choice its upload made. ## Response `202` Successful Response - ComparisonAcceptedResponse - `comparison_id` string, required: The comparison's id (cmp_...), which GET /v1/compare/{comparison_id} takes. - `redline_file_id` string, nullable: Deprecated: use file.file_id, the same id. Absent for a presentation or workbook comparison. - `status` 'processing', 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 ## 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)