Developer API

Everything you need to build powerful PDF generation workflows into your application.

Get Started

Introduction

PDFBridge is a powerful API for developers who need scale, security, and precision. All generated PDFs are stored according to your plan's retention policy (ranging from 7 to 30+ days) before being automatically purged, unless Ghost Mode is used.

Base URL / API Versioning

Production: v1 (Latest)

https://api.pdfbridge.xyz/api/v1

Authentication

PDFBridge uses a Dual API Key system. You are assigned two keys upon signup:

Test Key (pk_test_...)

Unlimited testing. Every PDF will have a large diagonal watermark. Does not count against your quota.

Live Key (pk_live_...)

Production usage. Clean PDFs. Usage counts against your plan's monthly conversion quota.

Include your key in the x-api-key header for all requests.

curl -X POST https://api.pdfbridge.xyz/api/v1/convert \
  -H "x-api-key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Usage & Credits

Each conversion job counts towards your plan's monthly credit limit. To ensure fair infrastructure usage, credits are calculated based on the final PDF file size.

Standard Credits

1 credit is deducted for any document up to your plan's base size limit (e.g., 10MB on Free Tier).

Dynamic Scaling

If a document exceeds the base unit, 1 extra credit is deducted per additional unit (or part thereof).

Calculation Table (Free Tier Example)

File SizeCredits DeductedExplanation
0.5 MB - 10.0 MB1Base cost
10.1 MB - 20.0 MB2+1 extra credit
20.1 MB - 30.0 MB3+2 extra credits

Convert PDF

Convert a public URL or raw HTML string into a PDF document. This operation is asynchronous and returns a jobId.

POST/convert
{
  "url": "https://stripe.com",
  "filename": "monthly_invoice_january",
  "webhookUrl": "https://your-app.com/api/webhooks/pdf",
  "ghostMode": true,
  "options": {
    "format": "A4",
    "printBackground": true
  }
}

Bulk Conversion

Process up to 1,000 conversions in a single request. Highly efficient for generating large sets of documents like monthly invoices.
POST/convert/bulk
{
  "jobs": [
    { "url": "https://site.com/doc1", "filename": "doc1" },
    { "url": "https://site.com/doc2", "filename": "doc2" }
  ]
}

Dynamic Templates

PDFBridge supports dynamic content injection using Handlebars-style variables. You can define placeholders like {{name}} in your HTML and provide values at conversion time.

Variable Syntax

Double-curly braces

Use {{variable_name}} anywhere in your HTML. Supports dot notation for nested objects (e.g., {{user.name}}).

Ad-hoc Usage

No template required

Pass variables directly with your raw HTML. The engine automatically detects and merges them before rendering.

Example Payload

{
  "html": "<h1>Hello {{name}}!</h1><p>Invoice #{{inv_id}}</p>",
  "variables": {
    "name": "Jane Doe",
    "inv_id": "99342"
  }
}

Options Reference

Page Formats

Available: A4, Letter, Legal, Tabloid, Ledger, A3

Standard Chromium paper sizes. Default is A4.

Set landscape: true or orientation: 'landscape' for horizontal layouts.

Custom Dimensions

paperWidth, paperHeight, preferCSSPageSize

Override standard formats with custom values (numbers in mm or strings like "10in").

Use preferCSSPageSize: true to respect @page rules in your CSS.

Precise Margins

marginTop, marginBottom, marginLeft, marginRight

Define margins globally via margin or use individual overrides for pixel-perfect control.

Supports numbers (mm) or strings (e.g., "0.5in", "20px").

Rendering Engine

waitDelay, userAgent, width, height

Tune the generator for complex sites. Default width is 1440px for URLs.

Use waitDelay: "5s" to wait for JS hydration or heavy animations.

Header & Footer

HTML Templates & Placeholders

Set displayHeaderFooter: true. Use these classes for dynamic data:

  • • pageNumber: Current page
  • • totalPages: Total pages
  • • date: Rendering date
  • • title: Document title

Set a document title via options.metadata.title to enable PDF/A compliance.

Tailwind-Native

PDFBridge features native support for Tailwind CSS. You can use any utility classes directly in your HTML payloads without manually linking stylesheets or configuring complex build pipelines.

How it Works

Automatic JIT Injection

When you set tailwind: true in your request:

  1. The engine automatically injects the Tailwind Play CDN script.
  2. The generator waits until the JIT compiler has fully rendered your styles before taking the snapshot.
  3. You get a pixel-perfect Tailwind PDF every time.

Example Payload

{
  "html": "<div class='bg-blue-600 p-12 text-white text-center rounded-3xl shadow-2xl'>
    <h1 class='text-4xl font-black mb-4'>Tailwind-Native</h1>
    <p class='text-blue-100'>No setup. No hacks. Just CSS utilities.</p>
  </div>",
  "tailwind": true
}

Team Management

Collaborate with your team seamlessly. Invite members, manage roles, and share templates across your organization.

Role-Based Access

Owners have full billing and seat control, while Members can create and manage templates.

Shared Resources

All templates and API keys are shared within the organization, ensuring consistent output.

Intelligent Extraction

PDFBridge features a high-performance extraction engine designed forFinancial Document Automation. Use the specialized/extract endpoint to upload existing PDF invoices and receive strict, typed JSON in seconds.

Bill To & Vendor Recognition

Zero Hallucination

Our model is fine-tuned to distinguish between the party issuing the invoice and the "Bill To" party, preventing metadata mismatches.

Direct Pipeline

Faster & More Secure

Uploading PDFs directly to /extractis 5x faster than rendering via headless browser.

Example Workflow (cURL)

curl -X POST https://api.pdfbridge.xyz/api/v1/extract \
  -H "x-api-key: pk_live_..." \
  -F "file=@invoice.pdf"

Job Polling Flow

Since PDF generation and AI extraction are complex asynchronous tasks, the API immediately returns a jobId. You should poll for the final result or rely on Webhooks.

Polling Example

// Poll every 1-2 seconds until status is SUCCESS
const response = await fetch("https://api.pdfbridge.xyz/api/v1/jobs/JOB_ID", {
  headers: { "x-api-key": "..." }
});
const job = await response.json();


if (job.status === "SUCCESS") {
  console.log("Extraction Results:", job.result.aiMetadata);
}

n8n Integration

Connect PDFBridge to 400+ applications using our custom n8n node. Automate your document generation workflows without writing code.

Professional Automation

No-Code Document Workflows

Our n8n Community Node allows you to integrate PDFBridge directly into your automated pipelines. Whether you're generating invoices from a database or summaries from web scrapers, the n8n node provides a visual interface for configuring every aspect of the conversion.

The node supports all core API features, including Tailwind-Native rendering, Intelligent PDF analysis, and custom formatting options, making it the ideal choice for enterprise-grade automation.

How to use it:

1
Install Node

In your n8n settings, go to "Community Nodes" and install:
n8n-nodes-pdfbridge

2
Add Your Secret Key

Copy your API Key from the dashboard and paste it into the node's credentials.

3
Start Printing!

Drag the PDFBridge node into your workflow, give it a URL, and watch the magic happen!

Webhooks

Set a webhookUrl in your request to receive a POST callback when document generation is finished or if it fails.

{
  "event": "pdf.generated",
  "jobId": "4ce4fc3a-2865-4404-933c-22da12f19679",
  "status": "completed",
  "url": "https://api.pdfbridge.xyz/api/v1/jobs/id/download"
}

Cryptographic Verification (HMAC-SHA256)

Every webhook sent by PDFBridge includes an X-PDFBridge-Signature header. This allows you to verify that the notification came from us and has not been altered in transit.

const crypto = require('crypto');


// The raw body of the POST request
const payload = JSON.stringify(req.body); 
const signature = req.headers['x-pdfbridge-signature'];
const secret = process.env.PDFBRIDGE_WEBHOOK_SECRET;


const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(payload).digest('hex');


if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))) {
  console.log("Verified! Process the PDF...");
} else {
  console.error("Invalid signature. Rejecting request.");
}

Webhook Inspector

Debug your integrations with our built-in Webhook Inspector. View delivery logs, response bodies, and latency for every attempt directly in the Usage Dashboard. Note: Webhooks are a paid-tier feature.

Ghost Mode (Privacy-First)

For sensitive documents, enable Ghost Mode by passing "ghostMode": true. The PDF will be generated, streamed to your webhook, and instantly deleted from our processing infrastructure.

Pricing & Tier Gating

Pro & Enterprise Only

Ghost Mode is exclusive to our Pro and Enterprise plans. It is designed for high-compliance environments where data must never touch persistent storage.

Zero-Storage Guarantee: When Ghost Mode is enabled, no records are stored in S3, and retention is set to 0 days.

Compliance & Security

Zero-Storage Policy

When Ghost Mode is enabled:

  • S3 storage is bypassed completely.
  • Retention days are set to 0.
  • Regeneration is unavailable (since the source HTML is not stored).

Node.js SDK

The official PDFBridge SDK for Node.js and TypeScript. Built with Zod runtime type-safety and performance in mind.

npm install @techhspyder/pdfbridge-node

Quick Start

import { PDFBridge } from '@techhspyder/pdfbridge-node';


// Automatically loads PDFBRIDGE_API_KEY from environment 
// or pass it explicitly: new PDFBridge({ apiKey: "..." })
const pdf = new PDFBridge();


async function run() {
  // Option 1: Generate & Wait for completion
  const result = await pdf.generateAndWait({
    url: 'https://example.com'
  });
  console.log('PDF URL:', result.pdfUrl);


  // Option 2: Ghost Mode (Renders as raw ArrayBuffer)
  const buffer = await pdf.generate({
    html: '<h1>Strictly Confidential</h1>',
    ghostMode: true
  });
}

Python SDK

Integrate PDFBridge into your Python applications with ease.

pip install pdfbridge-python

Example Usage

from pdfbridge import PDFBridge


# Automatically loads PDFBRIDGE_API_KEY from environment
client = PDFBridge()


# Generate and wait for completion
status = client.generate_and_wait(
    url="https://yourapp.com/invoice/123",
    options={"format": "A4", "printBackground": True}
)


print(f"PDF ready: {status.pdfUrl}")