Convert a file
Converts an uploaded file. Send the raw bytes as the request body with Content-Type set to the file's type. PullMD reads the raw body and doesn't decode multipart forms.
PDF, Word, PowerPoint, Excel, EPUB and ZIP files need the MarkItDown sidecar. PullMD reads e-mail, saved pages, text, subtitles, OpenDocument, RTF, calendars, contacts, data files, feeds, notebooks and source code itself; see Documents. Images and audio go to a vision or speech-to-text provider when one is configured, and to the MarkItDown sidecar otherwise. Without MARKITDOWN_URL, that request fails with 502. Nothing is cached: no history entry and no share link.
Authorizations
Needed only when the instance has sign-in enabled (PULLMD_AUTH_MODE is single-admin or multi-user). Send Bearer pmd_<key> with an API key created at /settings. In single-admin mode, the legacy PULLMD_AUTH_TOKEN is also accepted as a bearer token. OAuth access tokens work only on /mcp. Browser sessions use the pullmd_session cookie instead.
Query parameters
Original file name. Prefer the X-Filename header, which stays out of proxy access logs.
md returns Markdown, text strips the Markdown syntax, json returns the Markdown and its metadata in a JSON object.
Prepend a YAML block with the title, source URL, extractor, quality and other metadata. See Output format.
ocr sends PDFs to the OCR provider configured with PULLMD_PDF_OCR_API_KEY, which keeps tables intact. Without a provider, PullMD uses the standard conversion. Setting it bypasses the cache.
Language of the labels PullMD writes into e-mail, calendar, contact, notebook, data file and OpenDocument output. en gives English, and any other value gives German.
Which client to record for the request, in the history entry when the result is cached, and in the stats log. pwa records pwa. Any other value, or none, records the client detected from the User-Agent header (claude, browser or api). The X-Client-Mode header takes precedence over this parameter.
Headers
Original file name, URI-encoded. Used for the suggested download name and to help detect the file type.
Same as client_mode. Takes precedence over the query parameter.
Body
application/pdfThe file's raw bytes, up to 25 MB. PullMD accepts any Content-Type, and X-Filename or filename helps it detect the file type.
Response
200 · text/markdown, text/plain, application/jsonThe file as Markdown.
With format=json, the response is this JSON object.
The converted Markdown, including the frontmatter block when frontmatter=true.
Page metadata found during extraction. A field the source doesn't have is null. contentLength and extractorReason appear for pages extracted by Readability, Trafilatura or Playwright and for POST /api/html. Uploads and YouTube, image, audio, PDF OCR and MarkItDown results have contentLength without extractorReason, and Reddit, Hacker News and Cloudflare Markdown results have neither. A cached Reddit or Hacker News result has a shorter object with the fields it stores.
Which extractor produced the result. Same values as the X-Source header.
Share id, or null when the result was not cached.
Present only when query is set.
Response headers
Which extractor produced the result: cloudflare, readability, readability-fallback, trafilatura, playwright, recipe-content, coverage-guard, markitdown, youtube, reddit, hackernews, image-caption, audio-transcript, pdf-ocr, article-series, or for uploads PullMD reads itself email, text, markdown, subtitles, opendocument, rtf, calendar, contact, data, feed, notebook or code.
Extraction confidence from 0.0 to 1.0.
A download file name for the result, such as YT-some-talk-dQw4w9WgXcQ.md.