HTML to PDF

The HTML to PDF tool converts any HTML file into a pixel-perfect PDF. Use your own HTML and CSS — including frameworks like Tailwind CSS or Bootstrap — and get a print-ready document with customizable page settings.

How it works

Upload your HTML file via the file upload endpoint
Create a job via POST /tools/convert/html-to-pdf with the file ID and optional page settings
Poll the job via GET /tools/jobs/{jobId} until status is COMPLETED
Download the result via GET /tools/files/{fileId}/download

Basic request

At minimum, just provide the file ID of your uploaded HTML file:

{
  "fileId": "your-html-file-id"
}

This will produce an A4 portrait PDF with default margins (20mm top/bottom, 15mm left/right).

Full request with all options

{
  "fileId": "your-html-file-id",
  "format": "A4",
  "landscape": "landscape",
  "emulatedMediaType": "screen",
  "scale": 1.0,
  "preferCssPageSize": false,
  "margin": {
    "top": "25mm",
    "right": "20mm",
    "bottom": "25mm",
    "left": "20mm"
  },
  "headerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">My Report</div>",
  "footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
  "webhook": {
    "url": "https://example.com/webhook",
    "secret": "my-secret"
  }
}

Properties

Property	Type	Required	Default	Description
`fileId`	string	Yes	—	File ID of the uploaded HTML file.
`format`	string	No	`"A4"`	Page format: `"A4"`, `"A3"`, `"A5"`, `"Letter"`, `"Legal"`, `"Tabloid"`. Ignored when `preferCssPageSize` is enabled.
`landscape`	string	No	`"portrait"`	Page orientation: `"portrait"` or `"landscape"`.
`emulatedMediaType`	string	No	`"print"`	CSS media type: `"print"` or `"screen"`. See CSS media emulation.
`scale`	number	No	`1.0`	Scale factor between `0.1` and `2.0`. Values below 1.0 zoom out, above 1.0 zoom in.
`preferCssPageSize`	boolean	No	`false`	When enabled, any `@page` CSS rules in your HTML take priority over the `format` option.
`margin`	object	No	See below	Page margins. See Margins.
`headerTemplate`	string	No	—	HTML template for page headers. See Headers & Footers.
`footerTemplate`	string	No	—	HTML template for page footers. See Headers & Footers.
`webhook`	object	No	—	Optional webhook configuration for job completion notification.

Margins

Control the page margins using the margin object. Each value accepts a number with a unit (mm, cm, in, or px).

Property	Default	Example values
`top`	`"20mm"`	`"1in"`, `"2.54cm"`, `"72px"`
`right`	`"15mm"`	`"1in"`, `"2cm"`
`bottom`	`"20mm"`	`"1in"`, `"2.54cm"`
`left`	`"15mm"`	`"1in"`, `"2cm"`

{
  "margin": {
    "top": "25mm",
    "right": "20mm",
    "bottom": "30mm",
    "left": "20mm"
  }
}

When using headerTemplate or footerTemplate, make sure the corresponding margin (top or bottom) is large enough to display the header/footer content.

Headers & Footers

Add repeating headers and footers to every page of your PDF. Templates are standard HTML strings and support special placeholders for page numbers:

Placeholder	Description
`<span class="pageNumber"></span>`	Current page number
`<span class="totalPages"></span>`	Total number of pages

{
  "footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
}

Example: Custom header and footer

{
  "headerTemplate": "<div style=\"font-size:9px;width:100%;padding:0 20mm;\"><span style=\"float:left;\">Confidential</span><span style=\"float:right;\">ACME Corp</span></div>",
  "footerTemplate": "<div style=\"font-size:9px;text-align:center;width:100%;\"><span class=\"pageNumber\"></span> / <span class=\"totalPages\"></span></div>"
}

Header and footer templates must include their own inline styling (font-size, colors, etc.) — they do not inherit styles from your HTML document.

CSS media emulation

By default, the conversion uses print media emulation. This means CSS rules inside @media print will apply, and some CSS frameworks may behave differently than expected. Set emulatedMediaType to "screen" if you want the PDF to look exactly like it does in a browser — particularly useful when using CSS frameworks like Tailwind CSS or Bootstrap.

{
  "emulatedMediaType": "screen"
}

Value	Behavior
`"print"`	Standard print rendering. `@media print` rules apply. Best for documents designed for print.
`"screen"`	Screen rendering. All responsive and visual styles apply as in a browser. Best for web-designed HTML.

Page breaks

You can control page breaks directly in your HTML using standard CSS print properties:

/* Force a page break before an element */
h2 {
  break-before: page;
}

/* Prevent a page break inside an element */
.card {
  break-inside: avoid;
}

/* Force a page break after an element */
.section {
  break-after: page;
}

CSS `@page` rule

If you want full control over the page size and margins from within your HTML, use the CSS @page rule and enable preferCssPageSize:

<style>
  @page {
    size: A3 landscape;
    margin: 10mm;
  }
</style>

{
  "preferCssPageSize": true
}

When preferCssPageSize is enabled, the format and landscape API options are ignored in favor of your CSS rules.

Tips

External resources: The HTML file can reference external CSS, fonts, and images via URLs. These will be loaded during conversion.
Background colors: Background colors and images are always printed. No need for -webkit-print-color-adjust.
Maximum file size: The HTML file must be under 50 MB.
Timeout: The conversion allows up to 60 seconds for the page to load. If your HTML loads external resources, make sure they are accessible and responsive.

Overview

Document JSON Syntax

Tools Guides

Images

Rendering

Bulk Rendering

Projects & Documents

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

How it works

Basic request

Full request with all options

Properties

Margins

Headers & Footers

Example: Page numbers in footer

Example: Custom header and footer

CSS media emulation

Page breaks

CSS `@page` rule

Tips

​How it works

​Basic request

​Full request with all options

​Properties

​Margins

​Headers & Footers

​Example: Page numbers in footer

​Example: Custom header and footer

​CSS media emulation

​Page breaks

​CSS @page rule

​Tips

How it works

Basic request

Full request with all options

Properties

Margins

Headers & Footers

Example: Page numbers in footer

Example: Custom header and footer

CSS media emulation

Page breaks

CSS `@page` rule

Tips