Documentation

Overview

html2pdf.app is an HTML to PDF conversion API for developers. Send a public web page URL or raw HTML markup, and receive a ready-to-use PDF document in response.

Conversions run in headless Chromium, providing support for modern HTML, CSS, and JavaScript. The selected CSS media mode, available fonts and resources, and JavaScript load timing can affect the result, so test representative documents before using them in production.

Quick start

A standard conversion is one authenticated POST request. Send a public web page URL or raw HTML in the required html field, and the API returns the generated PDF as binary data.

EndpointPOST https://api.html2pdf.app/v1/generate

Request headerContent-Type: application/json

AuthenticationX-API-Key: <your-api-key>

Get an API keyCreate an account and use the API key sent after registration.
Choose the inputSet html to a publicly reachable URL or a raw HTML string.
Handle the resultCheck the HTTP status, then save or stream the successful response as a .pdf file.

Send your first request

Replace <your-api-key>, run the command, and cURL will write the generated PDF to document.pdf in the current directory.

curl --fail --show-error \
--request POST https://api.html2pdf.app/v1/generate \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <your-api-key>' \
--data '{
  "html": "https://www.example.com"
}' --output document.pdf

Handle the response

A successful synchronous request returns the PDF file as binary data. Do not parse it as JSON or text.
Check for a successful HTTP status before saving the body or sending it to a browser. The --fail option makes the cURL example fail on HTTP 4xx and 5xx responses.
To generate in the background, include callBackUrl and follow the callback workflow instead.

Continue with your language

Open a complete guide with production-oriented setup, PDF response handling, request options, and callback examples.

cURL PHP Node.js Python Ruby Java C# / .NET Go

View all code examples

Authentication

Authenticate every request by passing the X-API-Key header with your API key. You will receive your API key by email after registration.

Your API key is private. Use it from your backend, server-side scripts, or trusted jobs. Do not expose it in browser JavaScript, public repositories, or client-side templates.

Required header:

X-API-Key: <your-api-key>

Parameters

POST is recommended. Send parameters as a JSON request body to avoid query-string length and escaping problems. GET requests are also supported, but every query parameter must be URL-encoded; avoid GET for raw HTML and long template values.

Parameter	Type	Description	Default
html	`string`	Raw HTML markup or a publicly reachable URL to convert.	required
callBackUrl	`string`	Generates the document asynchronously and sends the result to this URL. The callback payload contains the base64-encoded PDF as `{"document": "..."}`. See Asynchronous requests & callbacks.	`null`
state	`string`	Optional value returned unchanged in the callback payload. Use it to associate the result with the original request.	`null`
landscape	`boolean`	Uses landscape instead of portrait page orientation.	`false`
format	`string`	Page format. Supported values: `Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6`	`A4`
width	`integer`	Custom page width in pixels. Use together with the `height` parameter.	`null`
height	`integer`	Custom page height in pixels. Use together with the `width` parameter.	`null`
marginTop marginRight marginBottom marginLeft	`integer`	Whitespace, in pixels, between the page edge and its content.	`0`
filename	`string`	Sets the filename returned with the generated PDF.	`null`
waitFor	`integer`	Number of seconds to wait before generating the PDF. Use this when the page needs time to finish JavaScript or load asynchronous resources. Supported range: `0` to `10`.	`0`
media	`string`	CSS media mode used while rendering. Supported values: `print` and `screen`.	`screen`
scale	`number`	Scale applied to the document content. Supported range: `0.1` to `2`.	`1`
headerTemplate footerTemplate	`string`	HTML markup rendered in the page header or footer. Use sufficient `marginTop` or `marginBottom` to make the template visible.	`null`
userPassword	`string`	Password required to open the encrypted PDF. Setting this value enables encryption.	`null`
ownerPassword	`string`	Owner password that grants full access to the encrypted PDF and its permissions.	`null`
permissions	`array`	Actions available to a user who opens the encrypted PDF. See the Encryption section for supported values.	`["print"]`

Asynchronous requests & callbacks

By default, the API keeps the request open while it generates the PDF and then returns the document as binary data. Provide a callBackUrl when the document should be generated in the background instead.

Submit an asynchronous job

Send the request to the normal generate endpoint and authenticate with the same X-API-Key header used for synchronous conversions. When authentication succeeds and the request is accepted for processing, the API responds with 202 Accepted. A 202 response is confirmation that the job was queued; its body is not the generated PDF.

curl --fail --show-error \
--request POST https://api.html2pdf.app/v1/generate \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <your-api-key>' \
--data '{
  "html": "https://www.example.com",
  "callBackUrl": "https://your-app.com/webhooks/pdf",
  "state": "order-123"
}'

Receive the generated PDF

When processing finishes, html2pdf.app sends a POST request to callBackUrl. The callback JSON contains the generated PDF as a base64-encoded document value. Decode that value before saving or serving the PDF.

{
  "document": "JVBERi0xLjQ...==",
  "state": "order-123"
}

The optional state value is returned unchanged, which lets you associate the callback with the original order, report, or job.

Callback delivery

Use a publicly reachable HTTPS endpoint that accepts POST requests.
Process callbacks idempotently because a failed delivery can be attempted more than once.
If callback delivery fails, html2pdf.app retries it up to three times. After the third retry fails, the delivery is marked as failed.

Errors and HTTP statuses

Check the HTTP status before treating a response as a PDF. A non-2xx response is an error and must not be saved or returned with an application/pdf content type.

Status	Meaning	Recommended action
`400`	The source URL is not accessible or a request parameter is invalid.	Confirm that the URL is publicly reachable and validate the request values before trying again.
`401`	The API key is missing or invalid.	Check the `X-API-Key` header and replace an invalid key.
`403`	The account has reached a limit included in its current plan.	Review the plan limits and the notification email sent to the account before retrying.
`500`	An unhandled server error occurred.	Retry after a short delay. Use increasing delays between repeated attempts and contact support if the error persists.

Do not automatically retry 400, 401, or 403 responses without first correcting the request, credentials, or account limit.

Fonts

The fonts listed below are available in the rendering environment.

You can also load Google Fonts or self-hosted web fonts with @font-face. Font stylesheets and files must be publicly reachable without authentication. If they load asynchronously, use waitFor to give the page time to finish rendering.

Fonts available in the PDF rendering environment
Andale Mono	Comic Sans MS	NotoSans	Verdana
Arial	Courier New	NotoSerif	Webdings
Arial Black	Georgia	Tahoma
Arial Narrow	Impact	Times New Roman
Arial Unicode	Microsoft Sans Serif	Trebuchet MS

Page breaks

Use CSS break rules to start each selected element on a new PDF page. Include the legacy page-break-* properties as a fallback.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Paginated HTML</title>
    <style>
      .page {
        break-after: page;
        break-inside: avoid;
        page-break-after: always;
        page-break-inside: avoid;
      }

      .page:last-child {
        break-after: auto;
        page-break-after: auto;
      }
    </style>
  </head>
  <body>
    <section class="page">
      <h1>This is page 1</h1>
    </section>
    <section class="page">
      <h1>This is page 2</h1>
    </section>
    <section class="page">
      <h1>This is page 3</h1>
    </section>
  </body>
</html>

Header and footer

Provide header and footer HTML with the headerTemplate and footerTemplate parameters. Use the following classes in the markup to insert document values at render time:

Class name	Description
date	Formatted print date
title	Document title
url	Document location
pageNumber	Current page number
totalPages	Total pages in the document

Reserve enough space for templates: use headerTemplate with a sufficient marginTop, and footerTemplate with a sufficient marginBottom.

Template code example

<div style="font-size: 12px; padding: 0 12px; width: 100%; text-align: center;">
  Page: <span class="pageNumber"></span> of <span class="totalPages"></span> |
  Date: <span class="date"></span> |
  Title: <span class="title"></span> |
  URL: <span class="url"></span>
</div>

Adding an image

Header and footer templates cannot load external resources. Embed images directly as base64 data URLs.

Put the base64-encoded image data in the src attribute.

<img src="data:image/png;base64,iVBORw0KGgo...AAAANSUh==" alt="" width="30" height="30" />

Using custom fonts

Header and footer templates do not inherit CSS from the source page. Include all required styles in the template markup.

You can use any of the rendering engine's supported fonts.

Template with custom CSS and image

<!doctype html>
<html>
  <head>
    <style>
      html {
        -webkit-print-color-adjust: exact;
        print-color-adjust: exact;
      }

      body {
        font-family: 'Arial Narrow', sans-serif;
        font-size: 12px;
      }

      .footer {
        width: 100%;
        padding: 0 12px;
        text-align: center;
      }
    </style>
  </head>
  <body>
    <div class="footer">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span> |
      Date: <span class="date"></span> |
      Title: <span class="title"></span> |
      URL: <span class="url"></span>
      <img
        src="data:image/png;base64,iVBORw0KGgoAAAA...kJggg=="
        alt=""
        width="30"
        height="30"
      />
    </div>
  </body>
</html>

Encryption

Set userPassword to encrypt the PDF and require a password when it is opened. Use permissions to control which actions are available after opening it. An optional ownerPassword grants full access to the document and its permission settings.

PDF encryption uses 128-bit AES.

Encryption is enabled when userPassword is set. By default, permissions is ["print"], allowing a user who opens the document to print it.

Parameter	Type	Description	Default
userPassword	`string`	The password that you want users to use for opening the PDF.	`null`
ownerPassword	`string`	Grants full access to the PDF, including actions restricted by `permissions` and the ability to modify those permissions.	`null`
permissions	`array`	Field controlling what actions a user entering userPassword can perform. `print` - allow printing. `modify` - allow document modification, signing, and form-field changes. `copy` - allow content copying and copying for accessibility. `edit` - allow commenting. `fillform` - allow filling of form fields. `extract` - allow content copying for accessibility. `assemble` - allow document assembly operations such as rotating, inserting, or deleting pages and managing bookmarks and thumbnails. `printbest` - allow high-resolution printing when `print` is also allowed.	`["print"]`

cURL request example

curl --fail --show-error --output example.pdf --request POST \
  --url https://api.html2pdf.app/v1/generate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "html": "https://example.com",
    "userPassword": "user",
    "ownerPassword": "owner",
    "permissions": ["print", "modify", "copy"]
}'

Data handling

Generated PDFs are processed only temporarily and are not permanently stored on our servers. Raw HTML or text submitted in the html parameter is not stored in conversion logs. Selected request metadata and a source URL supplied in html may be retained in those logs.

See the Privacy Policy and Data Processing Agreement for processing, retention, and security details.