Option reference

Generated from the same specification the API validates against, so this table and the accepted options cannot drift apart. Anything not listed here is a 400 invalid_request.

Request body

Field	Type	Default	Notes
`html`	string, ≤5000000 chars	—	The document to render. Mutually exclusive with url; exactly one is required.
`url`	string, ≤2000 chars	—	A public http(s) URL to render. Mutually exclusive with html.
`output`	binary \| url	binary	"binary" streams application/pdf back; "url" uploads and returns a signed link.
`filename`	string, ≤255 chars	document.pdf	Used for Content-Disposition on binary output and in the signed URL.
`headers`	object	—	url input only. Extra request headers, e.g. an Authorization header.
`cookies`	object	—	url input only. Array of {name, value, domain?, path?} seeded into the context.

Exactly one of html or url. Both, or neither, is a 400.

options

Option	Type	Default	Notes
`format`	A4 \| A3 \| A5 \| Letter \| Legal \| Tabloid	A4	Paper size. Ignored if the page CSS declares its own @page size.
`landscape`	boolean	false	Rotate the paper to landscape orientation.
`margin`	object	—	Page margins. Any side may be omitted; omitted sides default to 0.
`margin.top`	CSS length, e.g. "20mm"	—	e.g. "20mm", "1in", "72px".
`margin.right`	CSS length, e.g. "20mm"	—	e.g. "15mm".
`margin.bottom`	CSS length, e.g. "20mm"	—	e.g. "20mm".
`margin.left`	CSS length, e.g. "20mm"	—	e.g. "15mm".
`scale`	number 0.1–2	1	Rendering scale factor.
`printBackground`	boolean	true	Print background colours and images. Off by default in browsers; on by default here.
`pageRanges`	string, /^[0-9,\-\s]+$/	—	Subset of pages to keep, e.g. "1-5" or "1,4,7-9". Empty means all pages.
`headerHtml`	string, ≤50000 chars	—	HTML for the running header. Supports Chromium print classes: date, title, url, pageNumber, totalPages. Needs a top margin to be visible.
`footerHtml`	string, ≤50000 chars	—	HTML for the running footer. Same classes as headerHtml; needs a bottom margin.
`waitFor`	object	—	Conditions to satisfy before the PDF is taken. All of them apply, in order.
`waitFor.selector`	string, ≤500 chars	—	Wait until this CSS selector is attached to the DOM.
`waitFor.networkIdle`	boolean	false	Wait until there have been no network connections for 500 ms.
`waitFor.delayMs`	integer 0–30000	0	Fixed pause after the other wait conditions are satisfied.
`emulateMedia`	print \| screen	print	Which CSS media type the page sees.
`timeoutMs`	integer 1000–120000	30000	Hard ceiling on the whole render. Exceeding it returns 408 render_timeout.

Headers

Header	Direction	Notes
`Authorization`	request	`Bearer sk_live_…`. Required on every `/v1` endpoint.
`Idempotency-Key`	request	Same key and same body within 24 hours returns the original render instead of rendering — and billing — again.
`X-Renders-Remaining`	response	On every successful render.
`Retry-After`	response	Seconds to wait, on 429 rate_limited.
`X-Signature`	callback	HMAC-SHA256 of the raw callback body, keyed with your webhook secret.

Header and footer templates

headerHtml and footerHtml are rendered by Chromium in a separate document from the page. Two things trip people up: they inherit no page CSS, so set font-size inline, and they are invisible unless the matching margin leaves room for them. These classes are substituted: date, title, url, pageNumber, totalPages.

"headerHtml": "<div style='font-size:9px;width:100%;text-align:center'>Acme Ltd</div>",
"footerHtml": "<div style='font-size:9px;width:100%;text-align:right;padding-right:15mm'><span class='pageNumber'></span> / <span class='totalPages'></span></div>",
"margin": { "top": "20mm", "bottom": "20mm" }