---
title: "Render a URL or HTML to PDF"
method: POST
path: "/v1/pdf"
---

# Render a URL or HTML to PDF

`POST /v1/pdf`

## Request

- Base URL: `https://shotlane.dev`
- URL: `https://shotlane.dev/v1/pdf`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `access_key`

## Request body

- object
  - `url` string: Page to render (https:// assumed).
  - `html` string: Raw HTML to render instead of url (prefer POST).
  - `markdown` string: Markdown to render as a styled document instead of url/html (prefer POST).
  - `proxy` string: Your own proxy, e.g. http://user:pass@host:port (http, https, socks5).
  - `width` integer: Viewport width.
  - `height` integer: Viewport height.
  - `full_page` boolean: Capture the full scrollable page.
  - `scale` number: Device scale factor.
  - `selector` string: Capture only the first element matching this CSS selector.
  - `dark_mode` boolean: Emulate prefers-color-scheme: dark.
  - `hide_cookie_banners` boolean: Hide cookie consent banners.
  - `block_ads` boolean: Block ad and tracker requests.
  - `delay` integer: Extra wait after load (ms).
  - `wait_until` 'load' | 'domcontentloaded' | 'networkidle': Navigation wait condition.
  - `quality` integer: JPEG/WebP quality.
  - `cache_ttl` integer: Cache seconds; cache hits are free.
  - `response_type` 'file' | 'json': json: hosted 24 h link + details instead of the file.
  - `storage_bucket` string: Upload the result to this S3-compatible bucket (returns JSON).
  - `storage_key` string: Object key/path in the bucket.
  - `storage_endpoint` string: https endpoint for non-AWS storage (R2, B2, MinIO).
  - `storage_region` string: Bucket region (default us-east-1, or auto with an endpoint).
  - `storage_access_key_id` string: Access key for the bucket.
  - `storage_secret_access_key` string: Secret key for the bucket.
  - `storage_acl` 'private' | 'public-read': Object ACL.
  - `device` 'desktop' | 'desktop_hd' | 'laptop' | 'ipad' | 'iphone' | 'iphone_se' | 'pixel' | 'galaxy': Viewport preset.
  - `css` string: CSS to inject.
  - `js` string: JavaScript to run before capture.
  - `hide_selectors` string: Comma-separated selectors to hide.
  - `click` string: Selector to click before capture.
  - `wait_for_selector` string: Selector to wait for.
  - `headers` string: JSON object of extra headers (target host only).
  - `cookies` string: Cookies for the target URL, 'a=1; b=2'.
  - `timezone` string: IANA time zone, e.g. Europe/Berlin.
  - `locale` string: Browser locale and Accept-Language, e.g. de-DE.
  - `latitude` number: Geolocation latitude (with longitude).
  - `longitude` number: Geolocation longitude (with latitude).
  - `reduced_motion` boolean: Emulate prefers-reduced-motion.
  - `media_type` 'screen' | 'print': CSS media type.
  - `disable_js` boolean: Render without JavaScript.
  - `hide_popups` boolean: Close or hide sign-in/newsletter/app modals.
  - `block_trackers` boolean: Block analytics and tracking requests.
  - `block_chats` boolean: Block chat widgets (Intercom, Drift, Crisp...).
  - `block_requests` string: Comma-separated URL patterns to block (* wildcards).
  - `block_resources` string: Comma-separated resource types to block: image, media, font, stylesheet, script, xhr, fetch, websocket, other.
  - `hover` string: Selector to hover before capture.
  - `scroll_into_view` string: Selector to scroll into view before capture.
  - `wait_to_leave` string: Selector that must disappear first (e.g. a spinner).
  - `basic_auth` string: HTTP basic auth 'user:password' for the target origin.
  - `timeout` integer: Navigation timeout in seconds.
  - `fail_on_status` boolean: Fail (not charged) if the page answers 4xx/5xx.
  - `fail_if_content_contains` string: Fail (not charged) if the page text contains this.
  - `paper` 'A3' | 'A4' | 'A5' | 'Letter' | 'Legal' | 'Tabloid'
  - `landscape` boolean
  - `print_background` boolean
  - `margin` string: All margins, e.g. 1cm (or margin_top/right/bottom/left).
  - `page_numbers` boolean: Add a '1 / N' footer.
  - `header_template` string: Header HTML (pageNumber, totalPages, date, title, url classes).
  - `footer_template` string: Footer HTML.
  - `page_ranges` string: Pages to keep, e.g. 1-3, 5.
  - `pdf_scale` number
  - `pdf_width` string: Custom page width (with pdf_height), e.g. 100mm.
  - `pdf_height` string: Custom page height.
  - `watermark` string: Diagonal watermark text on every page.
  - `watermark_opacity` number
  - `pdf_password` string: Encrypt with this password (AES-256).
  - `pdf_title` string
  - `pdf_author` string
  - `pdf_subject` string
  - `pdf_keywords` string

## Response `200`

PDF

## Other responses

- `400`: Invalid parameters
- `401`: Invalid API key
- `402`: Out of credits
- `422`: Page could not be rendered

---

[API](https://skmtc.dev/shotlane/apis/shotlane-api.md) · [All operations](https://skmtc.dev/shotlane/apis/shotlane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shotlane/apis/shotlane-api/revisions/ce3f76e12e11?raw)