Web Page Conversion API#
The web pages endpoints render live URLs in a real browser and convert them into PDFs, full-page PNG screenshots, or clean GitHub-Flavored Markdown. Single-URL endpoints run synchronously (or asynchronously in batch), while the website endpoints crawl an entire site (via sitemap parsing or a full breadth-first crawl) and bundle every page into one ZIP archive. All endpoints share the same browser pipeline: cookie banner dismissal, lazy-load scrolling, sticky header handling, and support for pages behind HTTP Basic Auth, injected cookies, or custom headers.
Supported conversions#
| Conversion | Endpoint | Description |
|---|---|---|
| URL to PDF | POST /v1/convert/url-to-pdf |
Converts any publicly accessible URL into a high-fidelity PDF, with single-page continuous or paginated output, custom page sizes, headers/footers, and batch async mode. |
| URL to Screenshot | POST /v1/convert/url-to-screenshot |
Captures a full-page screenshot of any URL as a high-fidelity PNG, resizing the viewport to the true content height so the entire page is in one image. |
| URL to Markdown | POST /v1/convert/url-to-markdown |
Converts a web page into clean GitHub-Flavored Markdown with YAML frontmatter, using Readability extraction to strip boilerplate. Built for LLM and RAG ingestion pipelines. |
| Website to PDF | POST /v1/convert/website-to-pdf |
Crawls an entire website via sitemap or full breadth-first crawl, converts each discovered page to PDF, and bundles the results into a single ZIP archive. |
| Website to Screenshot | POST /v1/convert/website-to-screenshot |
Discovers every page of a website via sitemap or full crawl and captures a full-page PNG of each, delivered as one ZIP archive. |
Shared conventions#
- Authentication: Every endpoint accepts a private key in the
X-API-Keyheader; the three single-URL endpoints also accept public-key JWT Bearer tokens (restricted to a single URL, synchronous mode, and direct download), while the website endpoints require a private key. See Authentication. - Sync vs async: Single-URL endpoints run synchronously by default and switch to async (
async_mode=true, HTTP 202 with abatch_id) for batches; the website endpoints are always asynchronous. PollGET /v1/convert/batch/{batch_id}for results. See Sync and Async Jobs. - Responses: Completed conversions return a presigned download URL and
object_key; single-URL endpoints can instead return raw output bytes withdirect_download=true. - Browser and rendering parameters:
viewport_width/viewport_height,handle_cookies,enable_scroll,load_media,wait_for_images, andhandle_sticky_headerare shared across all five endpoints, as are theauth,cookies(max 50), andheaders(max 20) options for protected pages. See Sync and Async Jobs. - Errors and plan gating: All endpoints use the same status codes:
400for invalid input,401for bad credentials,402for quota or storage limits, and403for plan-gated features (async, webhooks, ZIP output, basic auth, website capture). See Error Codes.
Frequently asked questions#
Which endpoint should I use for a single page versus an entire website?#
Use url-to-pdf, url-to-screenshot, or url-to-markdown for one URL or an explicit list of URLs. Use website-to-pdf or website-to-screenshot when you want the API to discover the pages itself via sitemap.xml parsing or a full breadth-first crawl and return everything as one ZIP.
Can these endpoints convert pages behind a login?#
Yes, on plans with basic auth access. All five endpoints accept an auth object for HTTP Basic Auth, up to 50 injected cookies for session-based access, and up to 20 custom headers. These options are useful for staging sites, member-only pages, and dashboards.
How do I get the result of an asynchronous job?#
Async jobs return HTTP 202 with a batch_id immediately. Poll GET /v1/convert/batch/{batch_id} with your private key for per-URL statuses and presigned download URLs, provide a callback_url to receive a webhook POST on completion, or rely on the completion email sent to notification_email (the project owner by default).