PDF headers

Put your own header and footer on every PDF page

The report is generated. What makes it look generated is the page number Chromium puts there when you do not.

pdf_header_templatepdf_footer_templatepdf_margin_toppdf_margin_bottompdf_print_backgroundmedia_type

curl --fail-with-body "https://api.pagecapture.dev/v1/take" \
  -H "X-Access-Key: $PAGECAPTURE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com","format":"pdf","pdf_header_template":"<div style=\"font:9px system-ui;width:100%;padding:0 12mm;color:#555\">Monthly report</div>","pdf_footer_template":"<div style=\"font:9px system-ui;width:100%;padding:0 12mm;color:#555;text-align:right\"><span class=\"pageNumber\"></span> / <span class=\"totalPages\"></span></div>","pdf_margin_top":0.6,"pdf_margin_bottom":0.6,"pdf_print_background":true}' \
  -o capture.pdf

Verified 2026-08-13 by running the published code against a fixture.

Configure it in the playground

What it does

Takes HTML for either side and passes it to Chromium's print pipeline, so its page-number classes work as documented.
Fills only the side you left out with an empty span, so setting a footer does not silently give you Chromium's default header.
Accepts up to 128 KiB across both templates, checked during validation.

What it does not do

Does not run outside `format=pdf`. Any `pdf_*` parameter on a non-PDF request is rejected at validation instead of being ignored.
Does not inherit the page's stylesheet. The template is its own document and needs its own inline styles.
Does not create room for itself. Without `pdf_margin_top` or `pdf_margin_bottom`, the header renders into a margin of zero inches and disappears.

The contract

Every limit on this page is the one the API enforces

These rows are read from the same parameter table that validates your request. Nothing here is transcribed, so a number cannot drift from the behaviour it describes.

Parameter	Type	Default	Range	Endpoints	Cache key
`pdf_header_template` HTML rendered in the PDF header. Supports Chromium's date, title, url, pageNumber and totalPages classes.	string	—	—	/v1/take	In
`pdf_footer_template` HTML rendered in the PDF footer. Supports Chromium's date, title, url, pageNumber and totalPages classes.	string	—	—	/v1/take	In
`pdf_margin_top` Top margin in inches. Overrides `pdf_margin`.	number	—	0 – 10	/v1/take	In
`pdf_margin_bottom` Bottom margin in inches.	number	—	0 – 10	/v1/take	In
`pdf_print_background` Print CSS backgrounds.	boolean	false	—	/v1/take	In
`media_type` CSS media type to emulate.	enum	screen	—	/v1/take, /v1/animate	In

Group: PDFValues outside a documented range are rejected before a browser opens.

How it behaves next to the rest of the request

pdf_margin_top

Top margin in inches. Overrides `pdf_margin`.

Margins are in inches and default to 0. This is the single most common reason a header is set and not visible — the template is fine, the space is not there.

media_type

CSS media type to emulate.

Defaults to `screen` here, unlike raw Chromium, because most people want the PDF to look like the page. Switch to `print` when the site ships real print styles.

pdf_print_background

Print CSS backgrounds.

Background colours and images are dropped by default in print. Turn this on when the document's identity is in its background.

Errors this option can produce

request_not_validHTTP 400

The request is not valid.

timeout_errorHTTP 500 · retryable

The capture did not complete within the allowed time.

None of them is billable. No error code in the catalog is.

Questions this raises

How do I get page numbers?

Use Chromium's classes inside the template: `pageNumber`, `totalPages`, `date`, `title` and `url`. They are filled by the print pipeline, which is what these parameters feed.

My header is set but does not appear.

Check the margin. Header and footer render inside the page margin, and the default is zero inches — set `pdf_margin_top` or `pdf_margin_bottom` and it appears.

Can I use a web font in the template?

Only one the page already loaded, or one embedded inline. The template renders as its own small document and does not inherit the page's stylesheet.