DOCX to Markdown API

DOCX to Markdown converts Word files with headings, lists and tables; Excel, PowerPoint, OpenDocument, EPUB, RTF and HTML are also supported, with sheet tables and optional slide notes. AI agents can call and pay through Apify MCP.

The active Apify pricing record determines your bill; for the previous/checked schedules, document-converted previous/checked $0.002; usage is included and failed results are free.

Example result

Example record for the minimal input under How to use it, as this Actor returned it in its deploy check on 2026-10-16:

{
  "url": "https://raw.githubusercontent.com/python-openxml/python-docx/master/tests/test_files/test.docx",
  "ok": true,
  "format": "docx",
  "markdown": "# python-docx was here!\n\npython-docx was here too!",
  "sections": [],
  "truncated": false
}

How to use it

Start a run in Apify Console, by API or from an agent with an input like this one — it is the input Apify runs every day to test this Actor:

{"urls": ["https://raw.githubusercontent.com/python-openxml/python-docx/master/tests/test_files/test.docx"]}

Start with the minimal JSON example above, then adjust the fields in the table below. Read the Example result and Output fields sections for the returned record, Errors for failure codes, and Events and prices for result events and the separate platform start.

Field	Type	Required	Default	Meaning
urls	array of strings	yes	—	File URLs (.docx, .pptx, .xlsx, .odt, .odp, .ods, .epub, .rtf, .html), http or https, 1–50 per run, up to 50 MB each. The format is read from the file, not its name.
sheetRowLimit	integer	no	1000	Rows read from each spreadsheet sheet, the header row included (1–50,000).
includeNotes	boolean	no	true	Include each slide's speaker notes under a Notes heading.

Every limit above is enforced by the input schema and again in code.

Events and prices

The active Apify pricing record determines your bill; each schedule below is conditional on that exact record being active. A pending record does not authorise its charges. Before submission, while pending, and after activation, use the actual active record, not the requested calendar, to determine the bill.

Observed effective start: 2026-10-16T14:17:04.507Z, confirmed by the pricing record; this stage requests no pricing mutation.

Previous schedule — only if that record is active

apify-actor-start: FREE $0.00005, BRONZE $0.00005, SILVER $0.00005, GOLD $0.00005, PLATINUM $0.00005, DIAMOND $0.00005; document-converted: FREE $0.002, BRONZE $0.002, SILVER $0.0018, GOLD $0.0016, PLATINUM $0.0016, DIAMOND $0.0016.

Checked schedule — only if that record is active

Event	Title	Charged when	FREE / BRONZE	SILVER	GOLD / PLATINUM / DIAMOND
document-converted	Document converted	One file converted to Markdown.	$0.002	$0.0018	$0.0016

Platform event in the checked schedule: apify-actor-start: FREE $0.00005, BRONZE $0.00005, SILVER $0.00005, GOLD $0.00005, PLATINUM $0.00005, DIAMOND $0.00005.

The checked start at default memory is (2 events, $0.0001, at the default 2,048 MB).

Worked event subtotal, checked schedule at FREE: if 10 document-converted events are charged, 10 × $0.002 = $0.02 for that event alone. All other charged events and the platform start event add their listed fees; this subtotal is not a run total. The configured maximum-charge floor is $0.01. Platform usage is included; failed results are uncharged.

Call it from an agent

Through Apify's MCP server (https://mcp.apify.com), tool call-actor:

{"actor": "hermeskd/document-to-markdown", "input": {"urls": ["https://raw.githubusercontent.com/python-openxml/python-docx/master/tests/test_files/test.docx"]}, "callOptions": {"maxTotalChargeUsd": 0.05, "timeout": 600}, "waitSecs": 30}

The call returns the run's status and its defaultDatasetId. Read the records with get-dataset-items:

{"datasetId": "<defaultDatasetId from the call>", "limit": 50}

As a dedicated tool, add https://mcp.apify.com?tools=hermeskd/document-to-markdown to your MCP client. A single file finishes well inside the 30-second wait, so one call-actor plus one get-dataset-items is the whole exchange. maxTotalChargeUsd caps what the run can charge; when it is reached the remaining URLs come back as charge_limit_reached records and are not charged.

Output fields

One record per input URL.

Field	Meaning
url	The input URL.
ok	true when the document converted; false with error.
format	The format read from the file's bytes: docx, pptx, xlsx, odt, odp, ods, epub, rtf or html.
markdown	The document as Markdown. Word and OpenDocument text: headings, nested and numbered lists, tables, bold and italic, links. PowerPoint and OpenDocument presentations: ## Slide N: title, text as bullets by level, tables, notes. Excel and OpenDocument spreadsheets: ## Sheet: name and a table, the first row as its header. EPUB: the chapters in reading order. RTF: the paragraphs (styling is not read). HTML: the whole page body. Images and document properties are left out.
sections	For slides and sheets: {index, title} per slide or sheet, in order; empty for other formats.
truncated	true when a sheet had more rows than sheetRowLimit, or the Markdown was cut at 6 MB to fit one dataset record.
error	{code, message} when ok is false.

Limits and run time

• 1–50 URLs per run; files up to 50 MB; a zip-based file (Office, OpenDocument, EPUB) may unpack to at most 500 MB in at most 20,000 parts; up to 50,000 rows per sheet (1,000 by default).
• Each request — its redirects and its whole body included — must finish within 30 seconds (the per-request timeout; a slower file is download_failed); at most 2 requests a second go to one host.
• One record holds at most 6 MB of Markdown; a longer document is cut there and marked truncated.
• One document may take at most 120 seconds to convert; a file that needs longer is stopped and answered too_large, and the next document in the run starts fresh.
• Typical run time: a file converts in well under a second; a run of one file takes a few seconds at the default memory (2,048 MB). The default run timeout is 600 seconds.

Errors

Errors are records with ok: false and error.code; none is charged.

error.code	Meaning
download_failed	The URL did not return the file (status or network error).
unsupported_format	Not one of the listed formats (the message names the Hermes Actor for a PDF or an image; legacy .doc, .xls and .ppt are not read), a damaged file or one its reader cannot handle, or an archive over the unpacking limits.
encrypted	Password-protected, or an EPUB with DRM.
too_large	Larger than 50 MB, or too large or complex to convert within 120 seconds or within the converter's memory.
robots_disallowed	robots.txt forbids fetching the URL.
blocked_host	The host is on the deny-list, or resolves to a private or local address.
timeout	The document did not finish within the run's time budget.
internal_error	Unexpected failure; message carries the class.
charge_limit_reached	The run reached its maximum total charge before this URL; it was not processed.
invalid_input	The run input passed the input schema but cannot be used (for example no URL at all); the message names the field. One record per input given, or one with url: null when none was given; nothing is processed.

The run fails only when every input failed with an Actor-side code (internal_error, timeout), so a broken Actor is visible. Every other run succeeds — including one where nothing converted because of the caller's own inputs (bad URL, robots, deny-list, an unsupported or encrypted file, invalid input, the charge limit), or where those and Actor-side failures are mixed.

Sources and terms

The source is the caller's file. Process only documents you have the right to process. Fetching follows the Hermes fetch policy: robots.txt is obeyed for the user-agent HermesBot (and *), and a disallowed URL is refused without a request; platforms whose terms forbid automated access, and people-search sites, are on a deny-list and refused without a request; private and local addresses are refused, after DNS and on every redirect; the user-agent is HermesBot/1.0 (+https://apify.com/hermeskd); no login, cookies, credentials, CAPTCHA solving, evasion or proxies are used. Document properties — authors, last editor, comments (their text, author and date) and tracked-change authors — are never returned.

Not affiliated

This Actor is not affiliated with Microsoft, the Document Foundation, OASIS or the IDPF. mammoth, python-pptx, openpyxl, odfpy, markdownify, Beautiful Soup, lxml, striprtf and defusedxml are used under their open-source licences.

Related Hermes Actors

• AI Crawler Checker API — check declared robots.txt permissions for six AI crawlers at URL paths.
• Article Extraction API — an article's clean text, title and publish date, without the rest of the page.
• Career Site Job Search — Verified Greenhouse & Lever Boards — search open jobs in the Hermes directory of Greenhouse and Lever boards, each confirmed live.
• Speech to Text API — speech to text with SRT and VTT subtitles.
• Video Converter API — audio and video conversion: MP4 to MP3, trim, GIF.
• Broken Link Checker API — broken links, 404s and redirects on a site.
• Company ATS Finder — Which Hiring System & Job Board It Uses — which hiring system and job board a company uses.
• SEC Filings API — Read recent company financial filing metadata from the official SEC JSON API
• DOI Lookup API — crossref doi metadata.
• CVE Lookup API — look up NVD CVE dates, status, numeric CVSS scores and severity.
• JSON Deduplication API — json dataset cleaner.
• DNS Lookup API — DNS records and SPF, DKIM and DMARC checks.
• Domain Availability API — whether domain names are available, from registry RDAP.
• USGS Earthquake API — Read numeric USGS earthquake metadata for known event identifiers.
• ECB Exchange Rates API — Read latest ECB daily currency reference rates and calculated cross pairs.
• Bulk File Downloader API — files and images from URLs, saved with a public link each.
• GitHub Repo Stats API — Read numeric metrics for known public GitHub repositories.
• Greenhouse Job Board Scraper — Open Jobs, Live, Any Company — every open job on a company's Greenhouse board.
• Hacker News API — read numeric Hacker News story scores, timestamps and comment counts by ID.
• HTTP GET Request API — public http get.
• HTTP Security Headers Checker API — Check seven declared HTTP security header families without returning raw values.
• Background Removal API — Remove image backgrounds with the small U2NetP model and return transparent PNG pixels as base64
• Image Converter API — image format converter.
• Image Metadata Remover API — GPS location, camera serial numbers and other private metadata removed from photos, losslessly.
• Image to Text API — OCR: the text in images.
• Image Upscaler API — image upscaling 2x or 4x, and photo restoration.
• Lever Jobs Scraper — Postings from Any Lever Site, US & EU — every published job on a company's Lever site, global or EU.
• Lighthouse API — Lighthouse scores and Core Web Vitals.
• npm Package Metadata API — read latest npm package versions, license tokens and dependency counts.
• Website Change Detection API — what changed on a page since the last check.
• PDF to Markdown API — PDF to Markdown and text, with OCR for scanned pages.
• Public Holidays API — build offline public-holiday calendars for five countries and bounded years.
• Remote Jobs Scraper — Remote OK Listings, Salary Filter, Links — current remote jobs from Remote OK, with salary and listing links.
• Research Paper Search API — Search OpenAlex for work-level paper metadata without authors, affiliations, abstracts or full text
• RSS to JSON API — every item of an RSS, Atom or JSON feed.
• SEO Audit API — an on-page SEO audit: meta tags, schema, headings and links.
• Sitemap Extractor API — the URLs in a site's sitemaps.
• Text to Speech API — Convert short nonpersonal texts to offline formant WAV speech for agents
• Time Zone Converter API — Convert one offset-qualified instant to named IANA time zones using pinned data.
• URL to Markdown API — a public job page as clean Markdown where the site allows it (deny-listed job sites are refused).
• Extract Video Frames API — frames, thumbnails and scenes from a video.
• Website Color Palette API — Extract declared website CSS color literals and counts from public HTML and bounded linked stylesheets
• Favicon Extractor API — declared website icons, theme colors and manifest links.
• Website Screenshot API — screenshots and PDF prints of web pages.
• Website Technology Detection API — the technologies a website runs, detected live.
• Website Crawler API — bounded whole-site Markdown with robots and crawl-delay enforced

Changelog

• 1.0 (2026-10-26) — store listing rewritten for the people and agents searching for this job: title, description, search-engine title and description, categories, and the README in the order a searcher reads it (what it does, a real result, how to use it, prices, the agent call).
• 1.0 (2026-10-16) — comments in OpenDocument files are no longer read; a workbook with one far cell converts at once; a slide shape of unknown type is read as text; a file a reader cannot handle is unsupported_format, and one that cannot finish in 120 seconds is too_large.
• 1.0 (2026-10-16) — first release: nine formats, sheets as tables, slides as sections with notes, refusal of encrypted, damaged and oversized archives.