# Convert Word (.docx) to Markdown or HTML, with tracked changes and comments kept

> Upload a .docx and get Markdown where every tracked change is kept as CriticMarkup, {--deleted--}{++inserted++}, plus the reviewer comments and an HTML version with <del> and <ins>. Switch to final text only to see the document with all changes accepted. The tool runs Reducto Parse with r-1 and formatting.include change_tracking and comments, free.

Canonical: https://reducto.ai/tools/docx-to-markdown  
Last updated: 2026-11-15  
For: Developers giving agents Word files, Legal ops and paralegals, Contract and procurement teams, Teams building RAG over Word documents

## Run it now (free, no API key, up to 5 pages)

Send a PDF, Word, PowerPoint, Excel or image (PNG, JPG, HEIC, TIFF, BMP, GIF) (max 10 MB, 5 pages) to `POST https://reducto.ai/api/tools/docx-to-markdown` as multipart `file`, or JSON `{"url": "https://..."}`. The response has `result`, ready-to-save `output` (Markdown with CriticMarkup (.md), HTML with <del>/<ins> (.html), JSON (tracked, final and original text)), `pages_processed` and `next`.

```bash
curl -s https://reducto.ai/api/tools/docx-to-markdown \
  -F file=@northwind-msa-redline.docx

# or, for a file that is already online:
curl -s https://reducto.ai/api/tools/docx-to-markdown \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/northwind-msa-redline.docx"}'
```

Higher volume needs a free API key (new accounts get 15,000 free credits). Agents can sign up over HTTP: https://reducto.ai/auth.md. Humans: https://studio.reducto.ai/?utm_source=free_tool&utm_medium=agent&utm_campaign=docx-to-markdown&utm_content=api_response

Big file? Without a key the free run covers the first 5 pages and returns `partial: true` with a `signup_required` block. Your user signs up in under a minute (email, 6-digit code, name, terms: https://reducto.ai/auth.md); then repeat the same request with `Authorization: Bearer $REDUCTO_API_KEY` for the whole file on their 15,000 free credits. The same key works on the hosted MCP (https://mcp.reducto.ai/mcp) and the Reducto API.

## How to do it

1. Upload a Word .docx, or keep the sample.
2. Reducto Parse with r-1 reads the document with change tracking and comments turned on.
3. Each tracked change comes back inline; the tool writes it as {--deleted--}{++inserted++}.
4. Switch between tracked changes and final text only to check the result.
5. Copy the Markdown into your prompt or pipeline, or download Markdown, HTML or JSON.

## Reducto API call: `POST https://platform.reducto.ai/parse`

| Option | Value | Why |
| --- | --- | --- |
| `settings.model` | `"r-1"` | Returns each tracked change as one inline <change> tag with the inserted and deleted text. |
| `formatting.include` | `["change_tracking", "comments"]` | Keeps insertions, deletions and reviewer comments instead of flattening the document to one version. |
| `settings.page_range` | `{ start: 1, end: 5 }` | The free tool reads at most 5 pages. |

### curl

```bash
# 1. Upload the file (or pass a public URL as "input" and skip this step)
curl -s https://platform.reducto.ai/upload \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -F file=@contract.docx
# => {"file_id": "reducto://..."}

# 2. Run parse
curl -s https://platform.reducto.ai/parse \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "reducto://FILE_ID",
  "settings": {
    "model": "r-1",
    "page_range": {
      "start": 1,
      "end": 5
    }
  },
  "formatting": {
    "include": [
      "change_tracking",
      "comments"
    ]
  }
}'
```

### Python

```python
# pip install reductoai
from pathlib import Path
from reducto import Reducto

client = Reducto()  # reads REDUCTO_API_KEY

upload = client.upload(file=Path("contract.docx"))
result = client.parse.run(
    input=upload.file_id,
    settings={
        "model": "r-1",
        "page_range": {
            "start": 1,
            "end": 5,
        },
    },
    formatting={
        "include": [
            "change_tracking",
            "comments",
        ],
    },
)
print(result)
```

### Node

```ts
// npm install reductoai
import fs from "fs";
import Reducto from "reductoai";

const client = new Reducto(); // reads REDUCTO_API_KEY

const upload = await client.upload({ file: fs.createReadStream("contract.docx") });
const result = await client.parse.run({
  input: upload.file_id,
  settings: {
    model: "r-1",
    page_range: {
      start: 1,
      end: 5,
    },
  },
  formatting: {
    include: [
      "change_tracking",
      "comments",
    ],
  },
});
console.log(JSON.stringify(result, null, 2));
```

Do this with the API: [Convert PowerPoint (.pptx) and Excel (.xlsx) to Markdown for LLMs](https://reducto.ai/cookbooks/parse-pptx-xlsx-for-llms)

## What it handles

- **Keeps tracked changes and comments**: Insertions, deletions and comments are kept and marked, not silently accepted.
- **Insertions and deletions stay the right way round**: Added text and removed text are labelled as such.

## FAQ

### What is CriticMarkup?

A plain-text convention for edits: {--text--} is a deletion and {++text++} is an insertion. LLMs read it without any special setup, and it survives copy and paste.

### Why not just use python-docx or another Word reader?

Readers that walk the document's normal text runs skip tracked insertions and deletions. In our test on the sample contract, python-docx returned "The Customer shall pay each undisputed invoice .": the tracked change text was missing with no warning.

### Can I get the document with all changes accepted?

Yes. Choose final text only on the page, or use markdown_final in the JSON download. markdown_original has the text before the changes.

### Are comments kept?

Yes. Reviewer comments come through as text after the paragraph they belong to.

### What does the HTML output look like?

Headings, lists and paragraphs, with deletions in <del> and insertions in <ins>, so a browser or an HTML-aware model shows the redline.

### Does formatting survive?

Headings, lists, bold and italics come through as Markdown. Page layout, fonts and colors do not; this tool is for reading the content, not round-tripping the file.

### I want the changes as a table instead.

Use the redline to change list tool: one row per change with clause, inserted text, deleted text, context and comment, as CSV or Excel.

### Is it free?

Yes. Short documents run free with no account, with a small daily limit per IP. For a longer file you get a free preview of the first pages, then enter your email to get the whole file on a free account (15,000 free credits).

### Is there an API for this?

Yes. The snippet on this page is the exact Parse request. Tracked changes come back in result.chunks as <change><u>inserted</u><s>deleted</s></change>, which you can turn into CriticMarkup with two string replacements.

Sample document (synthetic): https://reducto.ai/office/samples/northwind-msa-redline.docx

## Related

- [Redline to change list](https://reducto.ai/tools/redline-to-change-list)
- [PDF to Word](https://reducto.ai/tools/pdf-to-word)
- [Scanned PDF to Word](https://reducto.ai/tools/scanned-pdf-to-word)
- [All Word tools](https://reducto.ai/tools/word)
- [Extract tracked changes from Word (API)](https://reducto.ai/cookbooks/reducto-parse-redlined-legal-contracts)
- [Edit a Word document with AI tracked changes](https://reducto.ai/office)
- [Read any document URL as Markdown](https://reducto.ai/read)
- [r-1 announcement](https://reducto.ai/blog/parse-r-1-model)
