pdfez docs

Greetings

Tired of breaking your stack just to get that chrome binary up and running? Ever wish you could just send a request and get a pdf without all the hassle? Keep your code where it belongs, run in any environement.

Introduction

Welcome to the docs! This page shows you exactly how to start generating perfect pdfs via the api. Download our postman/bruno collections or jump straight in with our code examples belows. pdfez aims to be the fastest, simplest and most development native way to generate pdf files.

A word about lock-in and privacy

pdfez is not for everyone and we don't want it to be. As your use case grows and changes, our goal is to make it as easy as possible for you to come up with your own solution. This is why pdfez only uses existing free tools and methods—such as Chromium for rendering and Handlebars for templating—and does not host any templates or documents. Instead, we encourage you to keep your templates within your own codebase. The goal of pdfez is simply to remove all the initial pain points of generating pdfs and get you going with the things that matter the most. All of our custom handlebars helpers will always be available for download, right here in the downloads section.

pdfez does not save or track the contents of your html, variables or the pdfs you generate. All sentitive information lives only in the context of each request and is processed in-memory. Our services are self-hosted in the EU and is fully compliant with GDPR. You are at any time able to withdraw your consent and delete all of your data from the settings page

Downloads

Download Postman Collection

Authentication

The API uses bearer auth to authenticate you. Grab your token and add it to the authorization header in your requests

Authorization: Bearer <YOUR_TOKEN>

The api offers two different key types. A live key for production use and a test key for staging or local use. Using the test key is free and does not incur costs, however a whitelabel will be added to any generated pdfs. You can use this key to get your design just right before switching to the live one, or use it in your staging environment.

Be aware that responses using the test key is much slower and generates larger pdfs than when using the live key.

Generating PDFs

All pdf generation starts at the /pdf endpoint. Send your html and get a pdf back in a single request. Use handlebars variables to inject and replace content in the generated pdf.

POST https://api.pdfez.io/pdf
curl -X POST https://api.pdfez.io/pdf \
-H "Authorization: Bearer <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
  "html": "<p>Hello, {{name}}!</p>",
  "variables": {
    "name": "Alice"
  }
}' --output document.pdf
html required

string

The html to be rendered. Provided as a raw string. Only one of html, html_base64 may be used.


html_base64 optional

string

The html to be rendered. Provided as a base64 encoded string. Only one of html, html_base64 may be used.


variables optional

object

Json object containing handlebars keys and values to replace in the given html or html_base64


options optional

object

Optional options objects where you can define margins, headers, footers and more. See the options reference below for all possible argumnets.


Response Types

Options

The following options control how the PDF is generated and rendered. You can customize page size, orientation, margins, scaling, headers, footers, and more. Each option is documented with its expected type, whether it's optional, and a description of its behavior.

Unless otherwise noted, all options are optional and will fall back to sensible defaults. Dimensions are expected in centimeters, and boolean flags default to false if omitted.

landscape optional

boolean

Whether to print the PDF in landscape orientation. Defaults to false.


print_background optional

boolean

Whether to print background graphics such as colors and images. Defaults to false.


scale optional

number

Scale factor for rendering the page. Defaults to 1. Accepts values above 0.


paper_size optional

enum

Predefined paper size to use. Must be one of: "A3", "A4", "A5", "Letter", "Legal", or "Tabloid".


paper_width optional

number (cm)

Custom paper width in centimeters. Must be a positive number. Used only when paper_size is not set.


paper_height optional

number (cm)

Custom paper height in centimeters. Must be a positive number. Used only when paper_size is not set.


margin_top optional

number (cm)

Top margin of the page in centimeters. Defaults to 1 cm (~0.4 inches).


margin_bottom optional

number (cm)

Bottom margin of the page in centimeters. Defaults to 1 cm (~0.4 inches).


margin_left optional

number (cm)

Left margin of the page in centimeters. Defaults to 1 cm (~0.4 inches).


margin_right optional

number (cm)

Right margin of the page in centimeters. Defaults to 1 cm (~0.4 inches).


display_header_footer optional

boolean

Whether to display headers and footers in the rendered PDF. Defaults to false.


header_html optional

string

HTML content for the header. Must be a valid HTML fragment and must not be empty when provided. Mutually exclusive with header_html_base64.

You can include dynamic values using the following class names. These will be automatically replaced in the output:

  • date – formatted print date
  • title – document title
  • url – document URL
  • pageNumber – current page number
  • totalPages – total number of pages

Example: <span class="title"></span> will be replaced with the document title.


footer_html optional

string

HTML content for the footer. Must be a valid HTML fragment and must not be empty when provided. Mutually exclusive with footer_html_base64.

You can include dynamic values using the following class names. These will be automatically replaced in the output:

  • date – formatted print date
  • title – document title
  • url – document URL
  • pageNumber – current page number
  • totalPages – total number of pages

Example: <span class="pageNumber"></span> will be replaced with the current page number.


header_html_base64 optional

base64 string

Base64-encoded HTML content for the header. Must not be empty when provided. Mutually exclusive with header_html.

You can include dynamic values using the following class names. These will be automatically replaced in the output:

  • date – formatted print date
  • title – document title
  • url – document URL
  • pageNumber – current page number
  • totalPages – total number of pages

Example: <span class="title"></span> will be replaced with the document title.



Limitations

pdfez sanitizes all user-supplied HTML before rendering to PDF, to ensure security and compatibility. While do we allow external assets such as fonts, stylesheets, images and icon libraries, we use a strict allowlist policy that allows only safe, commonly used HTML, CSS, and SVG features.

FAQ

  • Can I use external images?
  • Yes, by setting the src tag as you are used to.

  • Can I use custom fonts?
  • Yes, via external stylesheets (e.g., Google Fonts).

  • Can I use SVG logos or icons?
  • Yes, common SVG elements and attributes are supported.

  • Can I use JavaScript or forms?
  • No, for security reasons.

  • Can I use <style> and full CSS?
  • Yes, we allow this by design for PDF rendering, but be aware of the security tradeoff (see above).

What is Allowed

Formatting tagsb i u em strong a ul ol li p br span div blockquote code pre h1–h6
Tablestable thead tbody tr th td caption col colgroup
Imagesimg with src alt width height
Linksa with href title (only safe protocols: http, https, mailto)
Inline stylesstyle attribute
Embedded CSSstyle tag (see note below)
External stylesheets<link rel="stylesheet" href="...">
Font tagsfont with face color size
Class/id/data/aria attributesclass id data-* aria-* title alt
Horizontal rules and superscript/subscripthr sup sup
SVG graphicsCommon SVG elements and safe attributes (see below)
SVG Support
Elementssvg g path rect circle ellipse line polyline polygon text tspan defs linearGradient radialGradient stop symbol use view marker pattern clipPath mask filter feGaussianBlur feOffset feBlend feColorMatrix feComponentTransfer feComposite feFlood feImage feMerge feMorphology feTile feTurbulence
Attributeswidth height x y x1 x2 y1 y2 cx cy r rx ry d points fill stroke stroke-width opacity transform viewBox preserveAspectRatio offset stop-color stop-opacity gradientUnits gradientTransform xlink:href clip-path mask filter id class style

What is Blocked

Scripts<script> on* event attributes (e.g., onclick), and any executable code
Embeds<iframe> <object> <embed> <frame> <frameset>
Forms<form> <input> <button> <select> <textarea>
Media<video> <audio> <source>
OtherUnknown/unsupported tags and attributes