Convert a URL
Fetches a URL and returns the main content as Markdown. Web pages go through Cloudflare's native Markdown, Readability, Trafilatura and, for JavaScript-heavy pages, headless Chromium. Documents, YouTube videos, images and audio are converted when the matching sidecar or provider is configured.
Results are cached for one hour. A cached result is served unless you pass nocache or a parameter that changes the output. A request that bypasses the cache replaces the cached copy for that URL with its own result, so the next plain request is served that result.
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
The page, document, image or audio file to convert, or a YouTube video when MARKITDOWN_YOUTUBE is set. Reddit and Hacker News links are detected automatically.
A question about the page. PullMD returns only the sections that answer it. The PullMD README reports typically 70-95% fewer tokens on long pages. See Query-scoped extraction.
Token budget for query. No effect without query. With query, a value that isn't an integer from 64 to 20000 returns 400. A page of at most max(800, floor(1.25 × max_tokens)) estimated tokens comes back whole, even if that is over the budget: X-Extracted is false and X-Extract-Confidence is not sent.
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.
Skip the one-hour cache and fetch the source again.
Include the comment tree for Reddit and Hacker News links. false or 0 turns it off. Ignored for other URLs. A cached copy that has comments is served with them, so add nocache to fetch without comments.
Maximum comment nesting depth for Reddit and Hacker News, or all for the whole thread, including comments Reddit collapses. Any other value uses the default. Setting it bypasses the cache.
Reddit posts only: on or off describes and transcribes the images of the post with the vision model, overriding PULLMD_EMBEDDED_IMAGES unless that is off. Also accepts true, 1, false and 0.
Maximum number of top-level comments. PullMD reads the value as an integer up to its first non-digit, so 2.5 gives 2. Uncapped by default, and 0 or a value that doesn't start with a number also means no cap. Setting it bypasses the cache.
Language of the comments section heading. en gives ## Comments, and any other value gives ## Kommentare.
force always renders the page in headless Chromium, skip never does. By default PullMD decides per page. An unrecognized value is ignored. Setting it bypasses the cache.
Use one extractor and skip the automatic pick of the best result. An unrecognized value is ignored. Setting it bypasses the cache.
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.
YouTube transcript timecodes: links (clickable timestamp links), plain ([MM:SS] labels) or none. An unrecognized value is ignored. Setting it bypasses the cache. Without a valid value, the MarkItDown sidecar uses MARKITDOWN_YT_TIMECODES, which defaults to links.
Group the YouTube transcript into blocks of this many seconds. 0 keeps each original snippet. A value that isn't a whole number is ignored. Setting it bypasses the cache. Without a valid value, the MarkItDown sidecar uses MARKITDOWN_YT_CHUNK, which defaults to 30.
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
Same as client_mode. Takes precedence over the query parameter.
Response
200 · text/markdown, text/plain, application/jsonThe page 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.
32-character hex id of the cached copy. Open it at /s/<id>.
A download file name for the result, such as YT-some-talk-dQw4w9WgXcQ.md.
YouTube only. ok, none (the video has no transcript), or blocked / error, which are temporary and not cached.
Present when query is set. true when only matching sections were returned, false when the whole page was.
high, medium or low. Omitted when the page was small enough that extraction was skipped.
Number of sections included in the result.
Estimated tokens in the full page (characters divided by 4).
Estimated tokens in the returned Markdown.