Skip to main content

Convert HTML

POST/api/html

Converts an HTML document you send in the request body, such as a page saved from a browser. Use it for pages PullMD can't reach, such as pages behind a login.

Nothing is cached: no history entry and no share link. JavaScript in the document is never run, so an app shell with no server-rendered content returns 422.

Authorizations

Authorizationstringheader

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

urlstring<uri>

The page's original address. Used to resolve relative links and in the metadata.

extractorstring

Use one extractor and skip the automatic pick of the best result.

Available options: readabilitytrafilatura
formatstring

md returns Markdown, text strips the Markdown syntax, json returns the Markdown and its metadata in a JSON object.

Default: "md"Available options: mdtextjson
frontmatterboolean

Prepend a YAML block with the title, source URL, extractor, quality and other metadata. See Output format.

Default: false
filenamestring

Original file name. Prefer the X-Filename header, which stays out of proxy access logs.

client_modestring

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.

Available options: pwa

Headers

X-Filenamestring

Original file name, URI-encoded. Used for the suggested download name and to help detect the file type.

Example: report.pdf
X-Client-Modestring

Same as client_mode. Takes precedence over the query parameter.

Available options: pwa

Body

text/html

The raw HTML, up to 10 MB. Send it with Content-Type set to text/html or application/xhtml+xml.

stringstring

Response

200 · text/markdown, text/plain, application/json

The document as Markdown.

With format=json, the response is this JSON object.

markdownstring

The converted Markdown, including the frontmatter block when frontmatter=true.

metadataobject

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.

sourcestring

Which extractor produced the result. Same values as the X-Source header.

shareIdstring

Share id, or null when the result was not cached.

extractobject

Present only when query is set.

Response headers

X-Sourcestring

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.

X-Qualitynumber

Extraction confidence from 0.0 to 1.0.

X-Suggested-Filenamestring

A download file name for the result, such as YT-some-talk-dQw4w9WgXcQ.md.