---
title: "Convert HTML to PDF"
method: POST
path: "/v1/pdf"
---

# Convert HTML to PDF

`POST /v1/pdf`

Converts an HTML payload into a PDF document. Operates entirely in RAM for zero-retention compliance. Supports synchronous response or asynchronous delivery via webhooks.

## Request body

- object
  - `html` string, required — The raw HTML string to convert into a PDF.
  - `format` string — Optional page format such as A4, Letter, or Legal.
  - `width` string — Optional custom page width, e.g. 8.27in or 1200px. Overrides format when set.
  - `height` string — Optional custom page height, e.g. 11.69in or 1800px. Overrides format when set.
  - `landscape` boolean — Render the PDF in landscape orientation.
  - `scale` number — Scale factor between 0.1 and 2.
  - `pageRanges` string — Optional page ranges, e.g. 1-3, 5, 8-10.
  - `printBackground` boolean — Whether to include CSS backgrounds in the output.
  - `preferCSSPageSize` boolean — Prefer @page CSS size rules over the format option.
  - `headerTemplate` string — Optional HTML template for the PDF header. Must be valid HTML with inline CSS.
  - `footerTemplate` string — Optional HTML template for the PDF footer. Must be valid HTML with inline CSS.
  - `margins` object — Optional PDF margins.
    - `top` string
    - `right` string
    - `bottom` string
    - `left` string
  - `password` string — Optional password to encrypt the generated PDF (AES-256).
  - `waitUntil` string — Lifecycle event to wait for before rendering. Supported values: load, domcontentloaded, networkidle, commit.
  - `waitForSelector` string — Optional CSS selector to wait for before rendering.
  - `delayMs` integer — Optional extra render delay in milliseconds. Maximum 10000.
  - `viewport` object — Optional browser viewport size.
    - `width` integer
    - `height` integer
  - `webhookUrl` string, uri — Optional URL for asynchronous delivery. If provided, the API responds with 202 Accepted and POSTs the generated PDF to this URL.

## Response `200`

Successful synchronous PDF generation.

## Other responses

- `202` — Accepted for asynchronous processing via webhook.
- `400` — Bad Request (e.g., missing HTML).
- `401` — Unauthorized (missing API key).
- `402` — Payment Required (zero credits remaining).
- `403` — Forbidden (invalid API key).
- `500` — Server error while generating the PDF.

---

[API](https://skmtc.dev/xeropdf/apis/zero-retention-pdf-api.md) · [All operations](https://skmtc.dev/xeropdf/apis/zero-retention-pdf-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xeropdf/zero-retention-pdf-api/revisions/81d527a3ba1f/schema)