Convert a URL with progress

GET/api/stream

Same conversion as GET /api, delivered as Server-Sent Events so you can show progress. status events report each stage, and the stream ends with one result event or one error event. The web app uses this endpoint.

Errors after the stream has started, including blocked URLs, arrive as an error event rather than an HTTP status. To use query, call GET /api.

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>required

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.

Example: https://en.wikipedia.org/wiki/Markdown

frontmatterboolean

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

Default: false

nocacheboolean

Skip the one-hour cache and fetch the source again.

Default: false

commentsboolean

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.

Default: true

comment_depthstring

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.

Default: "3"

imagesstring

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.

Available options: onoff

comment_limitinteger

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.

langstring

Language of the comments section heading. en gives ## Comments, and any other value gives ## Kommentare.

Default: "de"Available options: deen

renderstring

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.

Available options: forceskip

extractorstring

Use one extractor and skip the automatic pick of the best result. An unrecognized value is ignored. Setting it bypasses the cache.

Available options: readabilitytrafilaturaplaywright

pdfstring

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.

Available options: ocr

yt_timecodesstring

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.

Default: "links"Available options: linksplainnone

yt_chunkinteger

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.

Default: 30Range: 0 ≤ x ≤ ∞

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-Client-Modestring

Same as client_mode. Takes precedence over the query parameter.

Available options: pwa

Response

200 · text/event-stream

An event stream of progress updates, ending with the result or an error.

Server-sent events. Each message is an event: line and a data: line holding a JSON object.

eventstring

status reports progress (any number of times), then exactly one result or error ends the stream.

Available options: statusresulterror

dataobject

The JSON payload. Its shape depends on event.

cURLcURLPythonJavaScript

curl --request GET \
  --url 'http://localhost:3000/api/stream?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FMarkdown' \
  --header 'Authorization: Bearer <token>'

event: status
data: {"stage":"fetching","url":"https://example.com"}

event: status
data: {"stage":"extracting","source":"readability"}

event: status
data: {"stage":"rendering","reason":"low quality (0.2)"}

event: status
data: {"stage":"extracting","source":"playwright"}

event: result
data: {"markdown":"# Example Domain\n\nThis domain is for use in documentation examples…","source":"playwright","shareId":"2f2f4a7b37f071b7e3137d42eb9dbec3","transcriptStatus":null,"suggestedFilename":"example-domain.md"}