Reference
Everything the PDF API does, and where each part is wrong
Every number on these pages is read from the running implementation rather than from a specification: payload ceilings, the six accepted page formats, the clamp on scale, two to twenty documents in a merge, per-plan batch sizes and retention. Nothing here describes a capability that does not exist.
Each page ends by saying where the option is the wrong tool, which is the part reference documentation structurally cannot say. For the complete parameter list including the parts with nothing interesting to say about them, use the API reference. For the CSS side of the same questions, see CSS for paged documents. If the caller is a workflow tool rather than your own code, what it can do with the response is the automation platform reference.
What you send
- Render HTMLPOST /v1/pdf with html
Send a complete HTML document in the request body and get the PDF bytes back in the response.
- Render a URLPOST /v1/pdf with url
Give an address instead of markup and the renderer fetches the page itself.
- Stored templatesPOST /v1/templates, then template_id
Upload the markup once, then render it by id with a data object, so the template lives on the server rather than in every caller.
The shape of the page
- Page formatoptions.format
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
- Marginsoptions.margin
One value for all four sides, or an object naming each side, defaulting to 1cm all round.
- Landscape orientationoptions.landscape
A boolean that turns the page rather than swapping its dimensions.
- Scaleoptions.scale
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
- CSS page sizeoptions.prefer_css_page_size
Tells the renderer to use the page box the document declares rather than a named format, which is how every non-standard size is reached.
- Page rangesoptions.page_ranges
A range expression that limits the output to specific pages of the rendered document.
How it renders
- Background graphicsoptions.print_background
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
- Print or screen mediaoptions.media
Chooses which CSS media type the document is rendered under: print by default, or screen when you want the page to look like the page.
- Running headers and footersoptions.header_html and options.footer_html
Small HTML fragments repeated on every page, with substitution tokens for the page number, the total, the date, the title and the URL.
- Presetsoptions.preset
Three named bundles of options for the three shapes most documents fall into, with anything you pass explicitly overriding them.
More than one document
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Combines between two and twenty PDFs into a single file, taking each one as a stored document id, a public URL, or base64 in the request.
- Stored documentsstore: true, then GET /v1/documents
Keeps a copy of the rendered document so it can be fetched again later, with a retention period that depends on the plan.
Getting it to the reader
Encrypts the output so a reader is asked for a password before the document opens.
- Render callbacksoptions.callback_url
An address notified after a render, so the calling code does not have to hold the request open waiting.
Usage and limits
- Usage and quotaGET /v1/usage
How many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.