API Reference

Everything you need to render HTML, URLs, and templates to PDF. All requests are authenticated with an API key in the Authorization header. Base URL: https://pdffleet.com

Authentication

Every request must include your API key as a Bearer token:

Authorization header

Authorization: Bearer tsa_pdf_your_key_here

Get a free key (50 PDFs/mo) or a paid key on the pricing page. Keys are tier-scoped: the tier determines your monthly PDF quota and requests-per-minute limit.

Render HTML to PDF

POST/v1/pdf

Send inline HTML and receive a rendered PDF as the response body (application/pdf).

Request body

Field	Type	Required	Description
html	string	one of html/url/template	Inline HTML document to render.
options	object	no	PDF rendering options (see options).

Example

curl

$ curl -X POST https://pdffleet.com/v1/pdf \
  -H "Authorization: Bearer tsa_pdf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Invoice</h1><p>Total: $1,500</p>","options":{"format":"A4","printBackground":true}}' \
  -o invoice.pdf

Returns: binary PDF file (Content-Type: application/pdf), HTTP 200.

Render a URL to PDF

POST/v1/pdf

Pass a URL and PDFFleet will load the page in headless Chromium, wait for it to render, then produce a PDF — useful for capturing live pages or your own internal app URLs.

Field	Type	Required	Description
url	string	one of html/url/template	Public URL to render to PDF.
options	object	no	PDF rendering options.

curl

$ curl -X POST https://pdffleet.com/v1/pdf \
  -H "Authorization: Bearer tsa_pdf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","options":{"format":"Letter"}}' \
  -o page.pdf

Render a template with data

POST/v1/pdf

Store a named HTML template containing {{field}} tokens, then render it repeatedly with different JSON data — ideal for invoices, reports, certificates, and receipts.

Field	Type	Required	Description
template	string	one of html/url/template	Name of a stored template to render.
data	object	yes (with template)	Key-value map merged into the template's `{{tokens}}`.
options	object	no	PDF rendering options.

curl

$ curl -X POST https://pdffleet.com/v1/pdf \
  -H "Authorization: Bearer tsa_pdf_your_key" \
  -H "Content-Type: application/json" \
  -d '{"template":"invoice","data":{"invoice_no":"1024","total":"1500.00","customer":"Acme"}}' \
  -o invoice.pdf

Template tokens: use {{field_name}} in your HTML. Nested keys like {{customer.name}} are supported. Missing fields render as empty strings.

PDF options

Pass an options object to control the PDF output. All fields are optional.

Option	Type	Default	Description
format	string	`"A4"`	Page size: `A4`, `Letter`, `Legal`, `A3`, `Tabloid`.
landscape	boolean	`false`	Render in landscape orientation.
printBackground	boolean	`false`	Include CSS background colors and images.
scale	number	`1`	Scale factor for content (0.1–2.0).
margin.top	string	`"0.4in"`	Top margin (e.g. `"0.5in"`, `"10mm"`).
margin.bottom	string	`"0.4in"`	Bottom margin.
margin.left	string	`"0.4in"`	Left margin.
margin.right	string	`"0.4in"`	Right margin.
displayHeaderFooter	boolean	`false`	Add a header/footer to each page.

Health check

GET/v1/health

No authentication required. Returns service status and browser readiness.

response

{
  "status": "ok",
  "service": "pdffleet-api",
  "version": "1.0.0",
  "browser": "chromium-ready",
  "timestamp": "2026-06-26T20:00:41.063Z"
}

Check usage

GET/v1/usage

Returns your current tier, this month's PDF count, and your remaining quota. Requires authentication.

response

{
  "tier": "hobby",
  "monthly_limit": 2000,
  "used": 142,
  "remaining": 1858,
  "period": "2026-06"
}

Rate limits & quotas

Requests are rate-limited per API key based on your tier:

Tier	PDFs / month	Requests / minute	Price
Free	50	20	$0
Hobby	2,000	60	$9/mo
Pro	50,000	300	$29/mo

Exceeding the rate limit returns 429 Too Many Requests. The monthly quota resets on the 1st of each calendar month.

Error responses

Code	Meaning
400	Bad request — missing or invalid `html`/`url`/`template`.
401	Unauthorized — missing or invalid API key.
403	Forbidden — monthly quota exceeded.
422	Unprocessable — invalid format or options.
429	Rate limited — too many requests per minute.
504	Render timeout — the page or HTML took too long to load.

Errors return JSON: {"error":"message","code":422}

SDK examples

Node.js

node

const fs = require('fs');

const res = await fetch('https://pdffleet.com/v1/pdf', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tsa_pdf_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    html: '<h1>Hello from PDFFleet</h1>',
    options: { format: 'A4' }
  })
});

const buf = Buffer.from(await res.arrayBuffer());
fs.writeFileSync('output.pdf', buf);

Python

python

import requests

resp = requests.post(
    'https://pdffleet.com/v1/pdf',
    headers={'Authorization': 'Bearer tsa_pdf_your_key'},
    json={'html': '<h1>Hello from PDFFleet</h1>',
          'options': {'format': 'A4'}}
)

with open('output.pdf', 'wb') as f:
    f.write(resp.content)

PHP

php

$ch = curl_init('https://pdffleet.com/v1/pdf');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer tsa_pdf_your_key',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'html' => '<h1>Hello from PDFFleet</h1>',
    'options' => ['format' => 'A4']
]));
$pdf = curl_exec($ch);
file_put_contents('output.pdf', $pdf);