API Reference

PDF Generation

Convert HTML to pixel-perfect PDFs with native Tailwind CSS support.

POST /pdf

Generate a PDF from HTML with automatic Tailwind CSS support. Supports sync and async modes.

Request Headers

Header Required Description
Content-Type Required Must be application/json
X-API-Key Required Your API authentication key
X-No-Store Optional Set to true to prevent HTML storage. Disables replay feature.

Request Body Parameters

content Required string

The HTML content to render. Tailwind CSS classes are automatically supported.

<div class="p-8 bg-white"><h1 class="text-2xl font-bold">Invoice</h1></div>
fonts Optional array

Google Font families to load. Use the format from Google Fonts URL parameters.

["Poppins:wght@400;600;700","Inter:wght@400;500"]
tailwind_config Optional object

Custom Tailwind configuration to extend or override defaults.

{"theme":{"extend":{"colors":{"brand":"#4F46E5"}}}}
css_id Optional string

ID of a pre-uploaded CSS asset. When provided, the CSS is injected

my-brand-styles-v2
pdfOptions Optional object

PDF output options for customizing paper size, orientation, margins, and scaling.

format a4
width
height
scale 1
landscape false
printBackground true
margin
viewport Optional object

Browser viewport dimensions for rendering. Controls the virtual browser window

width 1920
height 1080
deviceScaleFactor 1
waitFor Optional integer

Additional time to wait (in milliseconds) after page load before generating PDF.

Async Mode

Generate PDFs asynchronously and upload directly to your S3-compatible storage. Perfect for batch processing or when your client has short timeouts.

async Optional boolean

Enable async mode. When true, the API returns immediately with a job ID,

upload_url Required if async string

**Required when `async: true`**

webhook_url Optional string

**Optional, only used when `async: true`**

Async Response

{
  "job_id": "01JFXYZ123456789ABCDEFGH",
  "status": "pending",
  "status_url": "/jobs/01JFXYZ123456789ABCDEFGH"
}

Poll the status_url or wait for the webhook. See Async Jobs for details.

Password Protection

Business+ Plan

Encrypt PDFs with AES-256 encryption. Requires dedicated workers.

password Optional object

Password protection settings for the PDF.

user string

Password required to open/view the PDF

owner string

Password that grants full access (bypasses all restrictions)

permissions object

Restrictions: print, copy, modify, annotate (all boolean)

Password Example

{
  "content": "<div class=\"p-8\">Confidential Report</div>",
  "password": {
    "user": "viewonly123",
    "owner": "admin456",
    "permissions": {
      "print": true,
      "copy": false,
      "modify": false,
      "annotate": false
    }
  }
}

Paper Formats

A4 210 × 297mm
Letter 8.5 × 11in
Legal 8.5 × 14in
A3 297 × 420mm
A5 148 × 210mm
A6 105 × 148mm
Tabloid 11 × 17in
Custom width/height

Examples

Basic PDF

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-8\"&gt;&lt;h1 class=\"text-3xl font-bold text-gray-900\"&gt;Hello World&lt;/h1&gt;&lt;/div&gt;"
}' \
  --output output.pdf

With Google Fonts

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-8 font-[Poppins]\"&gt;&lt;h1 class=\"text-3xl font-bold\"&gt;Branded Document&lt;/h1&gt;&lt;/div&gt;",
    "fonts": [
        "Poppins:wght@400;600;700"
    ]
}' \
  --output output.pdf

With Custom Tailwind Config

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-8 bg-brand text-white\"&gt;&lt;h1 class=\"text-3xl font-bold\"&gt;Custom Colors&lt;/h1&gt;&lt;/div&gt;",
    "tailwind_config": {
        "theme": {
            "extend": {
                "colors": {
                    "brand": "#4F46E5"
                }
            }
        }
    }
}' \
  --output output.pdf

Custom Paper Size (Receipt)

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-2 text-sm\"&gt;&lt;h1 class=\"text-center font-bold\"&gt;RECEIPT&lt;/h1&gt;&lt;hr class=\"my-2\"/&gt;&lt;p&gt;Item 1 - $10.00&lt;/p&gt;&lt;/div&gt;",
    "viewport": {
        "width": 300
    },
    "pdfOptions": {
        "width": "80mm",
        "height": "200mm",
        "margin": {
            "top": "5mm",
            "right": "5mm",
            "bottom": "5mm",
            "left": "5mm"
        }
    }
}' \
  --output output.pdf

High-DPI Retina Output

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-8\"&gt;&lt;h1 class=\"text-3xl font-bold\"&gt;Sharp Text&lt;/h1&gt;&lt;/div&gt;",
    "viewport": {
        "width": 1920,
        "height": 1080,
        "deviceScaleFactor": 2
    }
}' \
  --output output.pdf

Async with S3 Upload

curl -X POST https://api.tailpdf.com/pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "content": "&lt;div class=\"p-8\"&gt;&lt;h1 class=\"text-2xl font-bold\"&gt;Invoice #1234&lt;/h1&gt;&lt;/div&gt;",
    "fonts": [
        "Inter:wght@400;600"
    ],
    "async": true,
    "upload_url": "https://my-bucket.s3.amazonaws.com/pdfs/invoice-1234.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
    "webhook_url": "https://api.example.com/webhooks/pdf-ready"
}'

Health Check

GET /health No auth required
200 Healthy 
{"status": "ok", "edge": true, "renderer": "cf-browser-rendering"}
503 Unavailable 
{"status": "error", "error": "Chrome not connected"}

Next up

Async Jobs