# PDF4.dev: Agent Instructions
## What this service does
PDF4.dev is a PDF generation API that lets developers create pixel-perfect PDFs from HTML templates. Design templates visually or in code using a Monaco-based editor with live preview, define dynamic fields with Handlebars {{variables}}, and generate PDFs via a simple REST API call from any language: TypeScript, Python, Go, Rust, PHP, or cURL. The rendering pipeline uses headless Chromium (Playwright) for accurate CSS support including flexbox, grid, and web fonts. PDF4.dev also provides a built-in MCP server so AI agents like Claude, ChatGPT, and Cursor can generate PDFs with natural language. Free browser-based PDF tools (merge, split, compress, convert) process files entirely client-side for privacy. Self-hostable via Docker with SQLite storage, PDF4.dev is a developer-first alternative to PDFMonkey, DocRaptor, and DIY Puppeteer setups.
## IMPORTANT: Base URL and HTTP methods
- Base URL: `https://pdf4.dev`. There is NO `api.pdf4.dev` subdomain. Always use `https://pdf4.dev/api/v1/...`.
- Supported HTTP methods: GET, POST, PUT, DELETE only. PATCH is NOT supported.
- Do NOT invent endpoints. There is no `/update`, `/edit`, or similar. Use PUT on the resource URL.
- Template body field is `html` (not `content`, `body`, or `template`).
## Authentication
All API calls require a Bearer token in the Authorization header:
```
Authorization: Bearer p4_live_xxx
```
Get an API key at: https://pdf4.dev/dashboard/settings
Two permission scopes:
- `full_access`: all endpoints (render, templates CRUD, components, logs)
- `render_only`: only POST /api/v1/render
## OpenAPI Specification
https://pdf4.dev/api/v1/openapi.json
## Primary Actions
### 1. Generate a PDF (most common)
```
POST https://pdf4.dev/api/v1/render
Content-Type: application/json
Authorization: Bearer p4_live_xxx
{
"template_id": "invoice",
"data": {
"company_name": "Acme Corp",
"invoice_number": "INV-001",
"total": "$1,500.00"
}
}
```
Response: `application/pdf` binary
You can also render from raw HTML instead of a template:
```json
{
"html": "Hello {{name}}
",
"data": { "name": "World" }
}
```
### 2. List templates
```
GET https://pdf4.dev/api/v1/templates
Authorization: Bearer p4_live_xxx
```
### 3. Create a template
```
POST https://pdf4.dev/api/v1/templates
Content-Type: application/json
Authorization: Bearer p4_live_xxx
{
"name": "Monthly Invoice",
"html": "Invoice #{{invoice_number}}
Amount: {{total}}
",
"sample_data": { "invoice_number": "INV-001", "total": "$1,000.00" }
}
```
### 4. View generation logs
```
GET https://pdf4.dev/api/v1/logs?limit=50&status=success
Authorization: Bearer p4_live_xxx
```
### 5. Create and attach header/footer components
Components are reusable HTML fragments shared across templates:
- **header**: repeats at the top of every printed page (rendered via `` in a table layout)
- **footer**: repeats at the bottom of every printed page (rendered via ``)
- **block**: renders inline where placed in the template HTML
**Managing components (MCP tools):**
- `create_component`: Create a header, footer, or block with `{{variables}}`. In footers, use `` and `` for page numbers.
- `list_components` / `get_component`: List or inspect components.
- `update_component` / `delete_component`: Modify or remove components.
- `create_template` / `update_template`: Attach header/footer via `header_component_id` and `footer_component_id` (comp_xxx IDs). Embed blocks in HTML with `Label`.
**Component HTML best practices:**
- Write components as **div fragments**, not full HTML documents. No ``, ``, or `` tags.
- Components **inherit parent template styles** (font, color, background). If `font_family` or `google_fonts_url` is set on the template's format, components use those fonts automatically.
- Keep component-specific styling inline or in a `