Documentation

Everything you need to integrate PDF API into your application. Build, test, and scale your document generation.

Authentication

All API requests must include your secret API key in the Authorization header. You can create and manage API keys from your dashboard.

Headers

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Keep your API keys secure. Never expose them in client-side code or public repositories. Use environment variables and rotate keys periodically from the dashboard.

Sandbox Mode

Testing your templates shouldn't cost you money. Add the X-PDF-Sandbox: true header to any request. Sandbox requests do not count against your monthly quota and are perfect for CI/CD pipelines and local development.

Note: Sandbox PDFs are automatically purged after 1 hour instead of the standard 24 hours. They also include a watermark indicating they were generated in sandbox mode.

Sandbox Request

curl -X POST https://api.pdfapi.dev/v1/render \ -H "Authorization: Bearer sk_live_xxx" \ -H "Content-Type: application/json" \ -H "X-PDF-Sandbox: true" \ -d '{"html": "<h1>Test</h1>"}'

POST

/v1/render

Generates a PDF from a raw HTML string or a pre-saved Template ID. Returns a JSON object containing a secure, time-limited URL to download the generated PDF.

Request Body

htmlstring (optional)

The raw HTML/CSS string to convert. Must be a complete document with <!DOCTYPE html>for best results. Supports all modern CSS including Flexbox, Grid, and custom properties.

template_idstring (optional)

The ID of a template saved in your dashboard. When provided, the template's HTML is used as the base and merged with the data object. Either html or template_id is required.

dataobject (optional)

JSON object containing variables to inject into the HTML template. Uses Handlebars-style syntax: {{variable_name}}. Supports nested objects and arrays for loops.

optionsobject (optional)

Rendering options including page_size (A4, Letter), orientation (portrait, landscape),margin_top, margin_bottom, header_html, and footer_html.

Response

200 OK

{
  "url": "https://cdn.pdfapi.dev/abc123.pdf",
  "expires_at": "2026-04-26T15:30:00Z",
  "pages": 3,
  "size_bytes": 45230
}

Templates

Templates let you save reusable HTML designs in your dashboard and render them with dynamic data. This keeps your API requests small and your document design centralized.

Create a template from the dashboard, copy its ID, and reference it in your render requests. Templates support Handlebars syntax for variables, loops ({{#each items}}), and conditionals ({{#if condition}}).

Pro tip: Use templates for invoices, reports, and any document with a consistent layout. Update the design once in the dashboard — all future renders automatically use the new version.

Webhooks

Configure webhooks to receive real-time notifications when PDFs are generated, deleted, or when your quota is approaching its limit. Webhooks are ideal for async workflows and monitoring.

Set your webhook URL in the dashboard. We send a POST request with a JSON payload containing the event type and relevant data. Verify webhook authenticity using the signature in theX-PDF-Signature header.

Webhook Payload

{
  "event": "pdf.generated",
  "timestamp": "2026-04-25T15:30:00Z",
  "data": {
    "job_id": "job_123",
    "url": "https://cdn.pdfapi.dev/abc123.pdf",
    "template_id": "invoice-template-01"
  }
}

Error Codes

PDF API returns structured error responses with a machine-readable code and a human-readablemessage. Always check the HTTP status code and handle errors gracefully in your application.

UNAUTHORIZEDHTTP 401

Invalid or missing API key.

RATE_LIMITEDHTTP 429

Too many requests. Slow down or upgrade your plan.

QUOTA_LIMIT_REACHEDHTTP 403

Monthly quota exceeded. Upgrade or wait for the next billing period.

INVALID_DATAHTTP 400

The provided JSON data does not match the template schema.

TEMPLATE_NOT_FOUNDHTTP 404

The requested template ID does not exist.

HTML_CONTENT_REQUIREDHTTP 400

Either html or template_id must be provided.

UPLOAD_TIMEOUTHTTP 504

The PDF was generated but the upload timed out. Retry the request.

Rate Limits

Rate limits vary by plan to ensure fair usage and platform stability. Limits are applied per API key and reset every minute.

Plan	Requests/minute	Concurrent
Free	10	2
Starter	60	5
Pro	300	20
Scale	1,000	50

Exceeding the rate limit returns a 429 Too Many Requests response. Retry with exponential backoff or upgrade your plan.

SDKs & Guides

While PDF API is a simple REST API that works with any HTTP client, we provide step-by-step integration guides for the most popular languages:

→ Node.js Guide → Python Guide → PHP Guide → Go Guide

Need help? Check our comparison with Puppeteer or contact us.