MarkItDown as an API

MarkItDown converts documents to Markdown for language models and text pipelines. It keeps headings, lists, tables and links from Word, PowerPoint, Excel and HTML files, and reads the text layer of a PDF. MarkItDown is a Microsoft open-source project.

Here it runs as an API: send a file to POST /v1/markitdown/convert and the Markdown comes back in the response. The file is converted in memory and not stored.

Price and limits

• With an API key, a conversion costs 1 credit. A rejected or failed call costs nothing.
• Without a key, the call runs at the anonymous rate limit and the daily free allowance of your internet address.
• One file per call, up to 8 MB. A conversion that takes longer than 30 seconds is stopped.
• The Content-Type of the file decides how it is read: application/pdf, the Office types of .docx, .pptx and .xlsx, text/html or text/plain.
• PDFs come back as the text of their text layer, without headings and without OCR. For scans, use OCRmyPDF first, or convert with Docling.

Plans and credit balances are on the pricing page. One balance pays for every engine.

Self-hosting or the hosted API

MarkItDown is a Python library and command-line tool. To self-host it you need Python 3.10 or newer, pip install 'markitdown[docx,pptx,xlsx,pdf]', and a web service of your own around it. Run each conversion in a separate process with a time limit, or one slow document blocks the service. Each warm worker process takes about 200 MB of memory.

The hosted API is one API key: no server to run, the conversion in killable worker processes with a 30-second limit, an MCP server for AI assistants, and the same key and credit balance for the other engines.

curl

curl -H "X-API-Key: YOUR_KEY" \
  -F "file=@report.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  https://api.pagespool.com/v1/markitdown/convert

The response is JSON. The Markdown is in markdown:

{"markdown": "# Quarterly report\n\nRevenue grew 8 percent in EMEA.\n\n...", "meta": {"filename": "report.docx"}}

Python

import httpx

with open("report.pdf", "rb") as fh:
    resp = httpx.post(
        "https://api.pagespool.com/v1/markitdown/convert",
        files={"file": ("report.pdf", fh, "application/pdf")},
        headers={"X-API-Key": "YOUR_KEY"},
        timeout=60,
    )
resp.raise_for_status()
print(resp.json()["markdown"])

Every error is a problem document (RFC 9457) with a code: payload_too_large (413), unsupported_media_type (415), conversion_failed (422), engine_busy (429, with Retry-After) or engine_timeout (504).

Sending the API key

The API takes the key in any of three forms:

• the header X-API-Key: YOUR_KEY;
• the header Authorization: Bearer YOUR_KEY;
• HTTP Basic authentication with the key as the password and any user name, as in curl -u x:YOUR_KEY. A client that takes only a base URL carries the key the same way, as https://x:YOUR_KEY@ in front of the host of https://api.pagespool.com. httpx and axios send that as Basic authentication.

Never put the key in the path or the query string: those end up in access logs.

MCP server

AI assistants reach MarkItDown at https://api.pagespool.com/mcp/markitdown/. Its tool convert_document takes the file as base64 or as a download link, with the same formats, limits and price as the API. The connect page has the steps for each client.

Free tools

Try the conversion in the browser, without an account: HTML to Markdown for pasted HTML up to 100 KB, and Word to Markdown for a .docx up to 4 MB.

MarkItDown is a Microsoft open-source project. MarkItDown is a trademark of its owner; pagespool is not affiliated.

FAQ

Can MarkItDown read scanned PDFs?

No. It reads the text layer of a PDF, so a scan comes back empty. Run the scan through OCRmyPDF first, or convert it with Docling, which runs OCR.

What does a conversion cost?

1 credit with an API key. A rejected or failed call costs nothing. Without a key, calls run at the anonymous rate limit and the daily free allowance.

Is my file stored?

No. The file is converted in memory, and the Markdown is returned in the response.