The shape of the page / options.format
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
What it is for
The fastest way to set the page when the document is going on standard paper. The value is a name rather than dimensions, which means it cannot be a millimetre wrong and it reads correctly to anyone who opens the code six months later.
The request
Sent to options.format. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"format": "Letter"
}
}The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- The accepted values are A4, A3, A5, Letter, Legal and Tabloid. Anything else returns 400 with a message listing the six.
- A4 is the default when format is omitted.
- Ledger is not a value. It is Tabloid with landscape set, because they are the same rectangle named by orientation.
- Every other size, from a 4 by 6 label to an 80mm receipt roll, is reached through the document's own page box rather than this option.
What failure looks like
An unrecognised value returns 400 immediately, before any rendering happens and before a document is metered. That is deliberate: a typo in a format name should cost nothing.
When this is the wrong tool
When the document declares its own page box in CSS. Setting the size in both places means two sources of truth that disagree, and which one wins is not something you should have to know. If the size belongs to the document, declare it there and set prefer_css_page_size instead.
Frequently asked
Is page format available on the free plan?
Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Set PDF margins in an API request
One value for all four sides, or an object naming each side, defaulting to 1cm all round.
Generate a landscape PDF from an API
A boolean that turns the page rather than swapping its dimensions.
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
Use the CSS @page size instead of a format
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.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render many PDFs in one API call
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.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.