API Reference

SDK

Official client libraries available on GitHub.

PHP

$pdf = new Funbrew\Pdf\FunbrewPdf('sk-your-api-key');
$result = $pdf->fromHtml('<h1>Hello</h1>');
echo $result['data']['download_url'];

Node.js

const { FunbrewPdf } = require('@funbrew/pdf');
const pdf = new FunbrewPdf('sk-your-api-key');
const result = await pdf.fromHtml('<h1>Hello</h1>');
console.log(result.data.download_url);

Python

from funbrew_pdf import FunbrewPdf
pdf = FunbrewPdf("sk-your-api-key")
result = pdf.from_html("<h1>Hello</h1>")
print(result["data"]["download_url"])

CLI

npm install -g @funbrew/pdf-cli
fbpdf config set-key sk-your-api-key
fbpdf html "<h1>Hello</h1>" -o hello.pdf

Authentication

All API requests require an API key. Include it as a Bearer Token in the request header.

Authorization: Bearer sk-your-api-key

X-API-Key You can also authenticate via the X-API-Key header or the ?api_key=... query parameter.

API keys can be issued from the dashboard. The key is shown only once at creation — store it securely.

Client / Project Grouping

Each API key can carry a client name and tags. Useful for agencies, contractors, and SaaS resellers running multiple customers or projects through one account — generated PDFs, API logs, and usage can all be filtered and aggregated per client.

When to use client_label vs tags

Rule of thumb: "unit you want to split invoices by" goes in client_label; everything else is a tag.

Use cases

• Reseller agencies: issue a dedicated key per client, filter PDF lists and API logs by client, and export CSV per client for invoice allocation.
• Multi-tenant SaaS: bundle keys per tenant, then add environment tags (production / staging / dev) for finer slicing.
• Contracted development: one key per project, so post-delivery support can pull only the relevant logs.

How to use

1. Dashboard → API Keys → click "New key" or "Edit" on an existing key.
2. Fill in the "Client / Project" field (e.g. Acme Inc) and optionally add tags (e.g. production, invoice-pdf).
3. Filter PDF list and API log pages by the new "Client" dropdown. CSV exports include a client_label column.

Client names are up to 100 chars, each tag up to 50 chars. Grouping is purely a management label — it does not affect API behavior or billing.

PDF Engine Selection

FUNBREW PDF offers two rendering engines. The default is the Chromium-based high-quality engine.

// Generate with Chromium engine (default)
{
  "html": "<div style='display:flex'>...</div>",
  "options": { "engine": "quality" }
}

When engine is not specified, quality (Chromium) is used. Use engine=fast for high-throughput batch generation.

Image formats: JPEG, PNG and GIF work on both engines. WebP and AVIF render only on the quality (Chromium) engine — they are not supported by the fast (wkhtmltopdf) engine.

Rate Limiting

API requests are subject to per-minute rate limits based on your plan.

Response Headers

All API responses include the following headers.

When Exceeded

When the limit is exceeded, a 429 Too Many Requests response is returned. Wait for the number of seconds in the Retry-After header before retrying.

{
  "success": false,
  "message": "Rate limit exceeded. Please retry later.",
  "retry_after": 42
}

HTML → PDF

Generate a PDF from HTML content.

Parameters

Request Example

curl -X POST https://your-domain/api/pdf/generate-from-html \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>", "options": {"page-size": "A4"}}'

Response

{
  "success": true,
  "data": {
    "filename": "uuid.pdf",
    "original_name": "請求書_2026年3月.pdf",
    "download_url": "https://.../api/pdf/download/uuid.pdf",
    "file_size": 45321,
    "expires_at": "2026-03-21T12:00:00.000000Z",
    "max_downloads": 10,
    "remaining_downloads": 10
  }
}

URL → PDF

Convert a web page specified by URL to PDF.

Template → PDF

Generate a PDF by injecting variables into a pre-registered template.

Markdown → PDF

Generate a styled PDF from Markdown text. Supports GFM (GitHub Flavored Markdown) including tables, code blocks, and checklists.

Parameters

Available Themes

Request Example

curl -X POST https://your-domain/api/pdf/generate-from-markdown \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello World\n\nThis is **bold** text.", "theme": "modern"}'

Related APIs

List available themes (no authentication required).

Convert Markdown to HTML for preview (no authentication required). Returns themed HTML output.

Batch Generation

Generate multiple PDFs asynchronously in batch.

Check batch progress status.

PDF Merge

Merge multiple existing PDFs into one.

Upload & Merge

Upload PDF files directly and merge them into one. You can also mix uploaded files with existing server files.

Content-Type: multipart/form-data

At least 2 files in total (uploaded + server filenames) are required.

curl -X POST https://pdf.funbrew.cloud/api/pdf/merge-upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[]=@invoice1.pdf" \
  -F "files[]=@invoice2.pdf"

Download

Download a generated PDF. Increments the download count.

File Info

Get PDF file metadata (size, remaining downloads, expiry, etc.).

File Delete

Delete a PDF file.

Template CRUD

List all templates.

Create a template. Use variable placeholders in html_content.

Email Delivery

Send generated PDFs as email attachments. Two methods are available.

A) Specify in API request

Add the email parameter to your generation request to send the PDF as an attachment after generation.

curl -X POST https://your-domain/api/pdf/generate-from-html \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>請求書</h1>",
    "email": {
      "to": "customer@example.com",
      "subject": "請求書をお送りします",
      "body": "添付の請求書をご確認ください。"
    }
  }'

B) Pre-configure in dashboard

Set up recipient, subject, and body templates in Email Notification Settings. Emails are sent automatically on every PDF generation.

The following placeholders can be used in subject and body:

Webhook / Slack Notifications

Register a webhook URL. Events are sent via POST.

Supported Events

Slack Integration

When you specify a Slack Incoming Webhook URL, notifications are automatically formatted as Slack Block Kit messages with download buttons.

Webhook and Slack notifications can also be configured from the dashboard.

Signature Verification

Standard webhooks include a X-Webhook-Signature: sha256=HMAC(payload, secret) header.

Usage

Returns current month's usage count, remaining quota, plan info, and enabled features.

S3 Storage Integration

Auto-upload generated PDFs to AWS S3 or S3-compatible services. When configured, PDFs are saved to both local and S3 storage, and the response includes an s3_url.

Configure from the dashboard. Also available via API:

Credentials are encrypted at rest on the server.

Error Codes

All error responses follow this format:

{ "success": false, "message": "Error description" }