Source documents
| Format | Compare | Merge | Edit |
|---|---|---|---|
.docx | Yes | Yes | Yes |
.doc | Yes | Yes | Yes, converted to .docx |
.pdf | Yes | Yes | Yes, converted to .docx |
.pptx | Two presentations, compared with each other | — | — |
.xlsx | Two workbooks, compared with each other | — | — |
Documents that are not already .docx are converted before comparison, so .doc and .pdf sources
spend noticeably longer in processing than .docx ones. A presentation or workbook can only be
compared with another of the same kind.
Redline PDFs
A PDF that is a redline, with insertions underlined in one color and deletions struck through
in another (blue and red, as Litera and Version Story print them), is converted with its
markup turned into tracked changes. Each insertion becomes a tracked insertion and each
deletion a tracked deletion, in body text, tables (including whole inserted or deleted rows),
headers and footers, and footnotes. Moved text, which Litera and Version Story mark in green,
becomes a deletion where it was and an insertion where it went. The redline's colors,
underlines and strikethroughs are removed, so accepting every change gives the revised text
and rejecting every change gives the original. The changes are attributed to Redline.
This is on by default. Send track_redline_changes=false with the upload to keep the markup
as plain formatting instead. The field is on POST /v1/files, POST /v1/compare and
POST /v1/merge. It applies to the documents that request uploads: a file already in Version Story keeps the choice its
upload made. A PDF that is not a redline, and every other kind of file, is unaffected.
In a comparison or a merge, a redline PDF therefore reads as its revised text, as a Word file
with pending tracked changes does (see
Keeping tracked changes).
With track_redline_changes=false, its struck-through text is read as part of the document.
Output formats
Pass the renderings you want as the format query parameter. It is repeatable and also accepts a
comma-separated list, so ?format=pdf&format=docx and ?format=pdf,docx both ask for two. A request
that names no format gets the Word file, so name pdf to show a redline.
format | Compare | Merge | Use it for |
|---|---|---|---|
pdf | PDF rendering of the redline | PDF rendering of the merged document | Showing a person the document. Start here |
html | The interactive redline, to embed | — | An interactive view beside the PDF |
docx | Word document with tracked changes (the default) | The merged Word document (the default) | A lawyer to review in Word and send on |
pdf_changed_pages_only | PDF of only the changed pages | — | A quick review of a long agreement |
md | The redline as Markdown | The merged document as Markdown | A model to read |
json | The redline as structured data | The merged document as structured data | Code that acts on the changes. Not for display |
pptx | Presentation redline (the default for two .pptx sources, whose only other format is pdf) | — | |
xlsx | Workbook redline (the only format for two .xlsx sources) | — |
Show people the PDF, embed the HTML where the view must be interactive, give a model the md, and
give your code the json. Never draw a redline from the json: it describes the document's structure
and changes, not its layout in pages. Why the PDF says more.
Renderings do not finish together: the PDF and the Markdown trail the Word document. A response
returns every requested format that is ready and names the rest in pending_formats, and reports
status: "ready" only once all of them exist. Asking for one format gets you an answer sooner than
asking for several.
Size and rate limits
| Limit | Value |
|---|---|
| Maximum file size | 100 MB per file |
| Revisions per merge | 2 to 10 |
| Edits per request | 200, and 200 KB of JSON |
| Pictures per edit | 20, at most 5 MB each and 25 MB in all |
| Suggested poll interval | 1 second, via Retry-After |
A request body larger than the biggest legitimate request (a ten-revision merge of 100 MB files) is
refused with 413 before it is read. Files larger than 100 MB need the in-app upload flow.
Expiry
Every download link is valid for one hour from issue. This is rarely a real constraint: the status endpoints mint fresh links on every call, so a finished result stays reachable; only the link itself ages out. Store ids or files, never links.
Retention
Results are kept, and stay downloadable, unless the organization turns on zero-day retention on the web app's Developer page. With it on, everything the API makes is permanently deleted an hour after it finishes, or as soon as you acknowledge the download, whichever is first. Data handling lists each kind of work and its acknowledge endpoint.
API trials
A new organization's API access starts as a trial, and some organizations are set up with one deliberately. A trial has three limits, shown on the Developer page's Overview tab:
- A comparison allowance. Each comparison and each edit counts once; a merge counts once
per revision. Uploads, status requests and downloads are free. When it is used up, new work is
refused with
403 TRIAL_COMPARISON_LIMIT_REACHED. - A per-minute rate. Requests past it are refused with
429 TRIAL_RATE_LIMITEDand aRetry-Afterheader saying how many seconds to wait. A merge with more revisions than the per-minute rate is refused outright with400 TRIAL_BATCH_TOO_LARGE. - Optionally, no Word downloads. A trial may exclude
docx: asking for it is refused with403 TRIAL_WORD_DOWNLOADS_EXCLUDED, and a request that names no format gets apdffor a comparison or an edit and anmdfor a merge instead.
Allowance and rate are checked before anything is created, so a refused request costs nothing. To move past a trial, talk to us.
Quotas
Organizations on a metered plan have a monthly document-upload allowance covering free
seats. When it is exhausted, the API returns 402 with code USAGE_LIMIT_REACHED. The check
runs before anything is created, so a rejected request costs nothing.
This is a billing state, not a transient failure; retrying will not clear it. Paid seats are not subject to the upload allowance.