Convert DOCX to Markdown

To convert DOCX to Markdown, send one POST to /v1/docx-to-markdown with the DOCX source. Each call costs $0.005 in USDC on Base via x402, with no account and no API key. The source file can be up to 25 MB.

Endpoint

POST /v1/docx-to-markdown

Price

$0.005 per call

Service

docx-to-markdown

Docs

/docs/docx-to-markdown

01Limits

02Example

A real DOCX to Markdown run of docx-to-markdown.

POST /v1/docx-to-markdown
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/documents/garden-handbook.docx"
}

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/documents/garden-handbook.docx",
  "chars": 341,
  "warnings": [],
  "markdown": "# Community Garden Handbook\n\nPlots are assigned for **one season** and renewed each spring.\n\n## Watering\n\n-   Water early in the morning.\n-   Use the rain barrels first.\n-   Log each watering on the shed board.\n\n## Tools\n\nReturn every tool to the shed _before sunset_.\n\nThe seasonal calendar lives on [the garden site](https://grist.tools/)."
}

Source file: documents/garden-handbook.docx, 2.8 KB (2,880 bytes). One-page Word document (community garden handbook): two heading levels, bold and italic runs, a three-item bullet list and one external link, hand-written OOXML with pinned zip dates. The recorded run returned 341 bytes of Markdown, 12% of the source size, with 341 characters.

The returned Markdown splits into 7 blocks separated by blank lines, with 3 headings (1 at level 1, 2 at level 2) reading "Community Garden Handbook", "Watering" and "Tools" and 3 bullet list items. Plain paragraphs make up 3 blocks, the first reading "Plots are assigned for **one season** and renewed each spring." and the last "The seasonal calendar lives on [the garden site](https://grist.tools/)." Its headings total 5 words, its paragraphs 29 words.

03Format notes

DOCX as a source

DOCX packages a Word document as OOXML inside a ZIP archive. The PK 03 04 signature passes the first gate, and mammoth must then find word/document.xml to accept the file as Word; a ZIP without it is refused. ZIP inflation is bounded on the real decompressed bytes before mammoth touches the buffer. Conversion runs in two stages: mammoth maps the document's styles to semantic HTML, covering headings, lists, bold and italic text, tables and links, and turndown renders that HTML as Markdown with ATX headings, fenced code blocks and hyphen bullets. Formatting that has no mapping is reported rather than hidden: mammoth's messages about content that did not translate come back as warnings, deduplicated so a repeated style problem appears once. Both libraries are imported only when a call arrives, and nothing is written to disk.

Markdown as a target

Markdown output comes from two kinds of source. Where the input already has document structure, docx-to-markdown and html-clean-text both hand HTML to turndown, which writes ATX headings, fenced code blocks and hyphen bullets. PDF offers only positioned text, so pdf-to-markdown infers headings from font size relative to the body size, and it does not rebuild tables, columns, figures or inline styles; its output is a transcription with no escaping of Markdown characters. For HTML, Readability keeps the main article by default; setting readability to false, or a page where no article is found, converts the whole body including navigation and footer. html-clean-text cuts both Markdown and text at max_chars, counted in Unicode code points, and flags a shortened result as truncated. The same call also returns plain text alongside the Markdown.

04Errors

When each is raised, and what it means for payment: /docs/docx-to-markdown.

05Questions

What does it cost to convert DOCX to Markdown?

$0.005 per call, paid in USDC on Base via x402.

How large can the DOCX file be?

Up to 25 MB (26,214,400 bytes). Past a limit the call answers too_large (413).

What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.

06Related

• Documents guide
• HTML to Markdown
• PDF to Markdown