Source documents
| Format | Compare | Merge / combine / version history |
|---|---|---|
.docx | Yes | Yes |
.doc | Yes | Yes |
.pdf | Yes | Yes |
Anything that is not already .docx is converted server-side before comparison, so .doc
and .pdf sources spend noticeably longer in processing than .docx ones.
Output formats
Over REST, pass the renderings you want as the format query parameter. It is repeatable
and also accepts a comma-separated list, so ?format=docx&format=md and ?format=docx,md
both ask for two:
format | Compare | Merge |
|---|---|---|
docx | Word document with tracked changes — the default | The merged Word document — the default |
pdf | PDF rendering of the redline | — |
pdf_changed_pages_only | PDF of only the changed pages | — |
md | Markdown rendering of the redline | Markdown rendering of the merged document |
Over MCP, pass them in download_options, or ["all"] for every available format:
| Operation | download_options value | Produces |
|---|---|---|
| Compare | word_redline | Word document with tracked changes |
| Compare | pdf_redline | PDF rendering of the redline — the default |
| Compare | pdf_changed_pages_only | PDF of only the changed pages |
| Merge | merged_docx | Merged Word document |
| Combine | combined_docx | Combined Word document |
| Version history | version_history_docx | Attributed Word document |
Note the different defaults. REST defaults to docx, the Word tracked-changes file.
MCP defaults to the comparison's previewable rendering, pdf_redline. Set the format
explicitly if it matters to you.
Renderings do not finish together — the PDF and the Markdown trail the Word document. A REST
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 | At least 2 |
Server-side URL fetch (create_comparison_from_links) | 100 MB, 30-second timeout, at most 3 redirects |
| Concurrent MCP uploads | 16 server-wide; a saturated server returns 503 with Retry-After: 1 |
| MCP upload request timeout | 300 seconds |
| MCP wait-tool budget | About 55 seconds per call, with keepalives every 5 seconds |
| REST suggested poll interval | 5 seconds, via Retry-After |
Files larger than 100 MB need the in-app upload flow rather than either API.
Expiry
Every signed URL — upload authorizations, upload manifests, download manifests, per-file
download URLs, and text_url — is valid for one hour from issue.
This is rarely a real constraint. The wait tools and the REST status endpoint mint fresh
URLs on every call, so a finished artifact stays reachable indefinitely; only the link
itself ages out. If an upload manifest lapses before its transfers happen, call the create
tool again with the same version_story_id to stage fresh ones.
Quotas
Organizations on a metered plan have a monthly document-upload allowance covering free seats. When it is exhausted:
- REST returns
402with codeUSAGE_LIMIT_REACHED. The check runs before anything is created, so a rejected request costs nothing. - MCP raises a tool error whose message includes an upgrade link.
This is a billing state, not a transient failure — retrying will not clear it. Paid seats are not subject to the upload allowance.