format=md gives a model the changes as text, so it can read them directly instead of unzipping a
.docx or re-deriving the diff from the source documents. It is working material for analysis, not a
deliverable: show a person the PDF redline (or the
HTML redline where the view must be interactive), hand them the Word redline
to edit, and give the model this.
Every md the API serves is the same listing: a comparison's redline (file in
GET /v1/compare/{comparison_id}, and the deprecated top-level downloads), a
merge's document, any file, an edit's two files, a
created document and a Document's versions. It is the document with each
paragraph's address and every change marked inline, the same text edits are written from. The
JSON is the same listing as structured data.
A redline as a listing
The listing opens with a header, an HTML comment explaining each tag it prints, then the document,
one paragraph per line. Each line starts with the paragraph's <p index="n" id="…"/> tag and holds
its text with every tracked change marked inline:
<p index="1" id="f4378834652a478eb5c67af7fa1b9eea" alignment="justify"/><b><smallcaps>This Non-Disclosure Agreement </smallcaps></b>(this “<b><i>Agreement</i></b>”) is entered into between <del revision="0" id="3e9a1c7b5d2f4e60a8b1c2d3e4f50617"><b><smallcaps>[COMPANY NAME]</smallcaps></b></del><ins revision="1" id="9f2c4e1a7b3d4c8e9a1f2b3c4d5e6f70"><b><smallcaps>Acme, Inc.</smallcaps></b></ins>, a Delaware corporation …
<p index="13" id="0b6e2f4a9c8d4e1f8a7b6c5d4e3f2a1b" label="7." list_level="1" style="ListNumber"/>Confidential Information is and shall remain the sole <ins revision="6" id="c71d2e3f4a5b4c6d8e9f0a1b2c3d4e5f">and exclusive </ins>property of the Company. …
<p index="15" id="7c1d0e9f8a2b4c3d9e8f7a6b5c4d3e2f" label="9." list_level="1"/>Confidential Information will not be reproduced in any form except as <del revision="12" id="0a4b8c2d6e1f4a3b9c7d5e2f1a0b9c8d">required</del><ins revision="13" id="5e6f7a8b9c0d4e1f8a2b3c4d5e6f7081">is strictly necessary</ins> to accomplish the <del revision="14" id="d2e3f4a5b6c74d8e9f0a1b2c3d4e5f60">intent</del><ins revision="15" id="7b8c9d0e1f2a4b3c8d4e5f6a7b8c9d0e">purpose</ins> of this Agreement. …After the body come the headers and footers, notes and comment threads, then one line per revision:
<revision index="0" id="3e9a1c7b5d2f4e60a8b1c2d3e4f50617" type="deletion" author="Dana Reyes" date="2026-10-22T03:37:30Z"/>
<revision index="1" id="9f2c4e1a7b3d4c8e9a1f2b3c4d5e6f70" type="insertion" author="Dana Reyes" date="2026-10-22T03:37:30Z"/>| Element | Meaning |
|---|---|
<p index="n" id="…"/> | Starts a paragraph: its index and id, which an edit names. A numbered paragraph adds its label and list_level; style is printed where it changes |
<ins revision="n" id="…"> | Text the later version inserted |
<del revision="n" id="…"> | Text the later version deleted |
<moved-from revision="n" id="…"> / <moved-to revision="n" id="…"> | Where moved text was, and where it is now. Both halves name the same revision |
<revision index="n" id="…" type="…" author="…" date="…"/> | One line per revision, after the body. A revision no element shows, such as a formatting or paragraph mark change, also prints what it changes (on), where (part, paragraph, or its table, row or cell), and the start of its text |
revision on a change element is the index of its <revision/> line and id is that revision's id: the
{"index": n} or {"id": "…"} that an add_comment or a
revision decision names, and the id the HTML redline marks the change with. Who made a
change and when is on that line, once, rather than on every element. Changes nest when revisions
changed the same text, so both attributions survive.
Tables print as <table index id rows columns>, <row index id/> and <cell index id column/> lines,
with span on a merged cell; equations as <equation>…</equation>; pictures as
<picture index="n" id="…"/>. Sections, headers, footers, notes and comment threads print their
index and id too (<section index id/>, <header index id type section>, <footnote index id>,
<comment index id>): every element with an index has an id, the same as in the
JSON and the HTML. A list paragraph's number is its label attribute, never text. The listing's
own header says what every tag it prints means.
Merged documents
A merge's Markdown is the same listing. Each revision's author is its label, the name and the
revision's file name, so the <revision/> lines say which draft each change came from. Where two
revisions changed the same words differently, both changes are shown, each naming its revision:
the original words are deleted once, credited to both revisions, and each replacement is inserted
beside it.
<p index="31" id="5e4d3c2b1a0f4e9d8c7b6a5f4e3d2c1b"/>"Accounts Date" means <conflict index="0" id="8c1e5a9d3b7f4e2a6c0d8b4f2e6a1c3d"><del revision="3" id="0a4b8c2d6e1f4a3b9c7d5e2f1a0b9c8d">[•]</del><ins revision="4" id="5e6f7a8b9c0d4e1f8a2b3c4d5e6f7081">April 15, 2027</ins><ins revision="5" id="d2e3f4a5b6c74d8e9f0a1b2c3d4e5f60">December 31, 2026</ins></conflict>;
…
<revision index="4" id="5e6f7a8b9c0d4e1f8a2b3c4d5e6f7081" type="insertion" author="Dana Reyes — nda_from_counsel.docx" date="2026-10-22T03:37:30Z"/>
<revision index="5" id="d2e3f4a5b6c74d8e9f0a1b2c3d4e5f60" type="insertion" author="Sam Patel — nda_from_finance.docx" date="2026-10-22T03:41:02Z"/>Each set of competing changes is wrapped in a <conflict index id> element, as the
JSON wraps it in a conflict segment. Surface these to a
person; do not resolve them automatically.
Reading a long listing
The listing of a long document can be large. GET /v1/files/{file_id}?format=md can return only the
paragraphs that hold a phrase, or the listing in parts; see
Reading the listing.
md is not offered for presentation or spreadsheet comparisons. The docx redline carries the same
set of tracked changes either way.