> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fileloom.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate PDF
> Generate a PDF from HTML content or a saved template.
Generate a PDF document from raw HTML or a saved template with dynamic data.
## Endpoint
```
POST https://api.fileloom.io/v1/pdf/generate
```
## Authentication
Include your API key in the request headers:
```
X-API-Key: fl_your_api_key
```
## Request Body
You must provide either `htmlContent` OR `templateId`, but not both.
### Using Raw HTML
```json theme={null}
{
"htmlContent": "Hello {{name}}
",
"templateData": {
"name": "World"
},
"filename": "greeting.pdf",
"options": {
"format": "A4",
"orientation": "portrait",
"margin": {
"top": 10,
"right": 10,
"bottom": 10,
"left": 10
},
"printBackground": true
}
}
```
### Using a Template
```json theme={null}
{
"templateId": "tpl_abc123xyz",
"templateData": {
"invoiceNumber": "INV-2024-001",
"customer": {
"name": "Acme Corp",
"email": "billing@acme.com"
},
"items": [
{"name": "Widget", "price": 29.99, "quantity": 2},
{"name": "Gadget", "price": 49.99, "quantity": 1}
],
"total": 109.97
},
"filename": "invoice-INV-2024-001.pdf"
}
```
## Parameters
### Required (one of)
Raw HTML content to convert to PDF. Supports Handlebars syntax for dynamic content.
ID of a saved template to use. Find this in the template editor or templates list.
### Optional
JSON object with data to inject into Handlebars placeholders.
Custom filename for the generated PDF (without .pdf extension). Max 255 characters.
PDF generation options. When using a template, these override template settings.
### Options Object
Paper size. One of: `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `Letter`, `Legal`, `Tabloid`, `Ledger`, `Custom`
Page orientation. One of: `portrait`, `landscape`
Custom page width in millimeters. Only used when format is `Custom`.
Custom page height in millimeters. Only used when format is `Custom`.
Page margins in millimeters.
```json theme={null}
{
"top": 10,
"right": 10,
"bottom": 10,
"left": 10
}
```
Include background colors and images in the PDF.
Page header configuration.
```json theme={null}
{
"enabled": true,
"height": 15,
"content": "Header
"
}
```
Page footer configuration.
```json theme={null}
{
"enabled": true,
"height": 10,
"content": "Page
"
}
```
Dynamic filename template using Handlebars syntax. Example: `Invoice-{{invoiceNumber}}`
## Response
### Success Response (200)
```json theme={null}
{
"success": true,
"requestId": "req_1734012345_abc123",
"data": {
"fileId": "file_1734012345_xyz789",
"url": "https://storage.googleapis.com/fileloom-prod/workspaces/ws_xxx/pdfs/2024/12/document-1734012345.pdf",
"signedUrl": "https://storage.googleapis.com/fileloom-prod/workspaces/ws_xxx/pdfs/2024/12/document-1734012345.pdf?X-Goog-Algorithm=...",
"filename": "document.pdf",
"size": 12847,
"expiresAt": "2024-12-16T10:30:00.000Z",
"storageProvider": "firebase",
"processingTimeMs": 847,
"generationMethod": "html",
"templateUsed": null
},
"usage": {
"remaining": 1999,
"quotaUsed": 1,
"quotaLimit": 2000
}
}
```
### Response Fields
| Field | Type | Description |
| ----------------------- | ------- | ---------------------------------------------------- |
| `success` | boolean | Whether the request succeeded |
| `requestId` | string | Unique identifier for this request |
| `data.fileId` | string | Unique identifier for the generated file |
| `data.url` | string | Permanent public URL (valid until retention expires) |
| `data.signedUrl` | string | Temporary signed URL (valid for 24 hours) |
| `data.filename` | string | Filename of the generated PDF |
| `data.size` | number | File size in bytes |
| `data.expiresAt` | string | When the signed URL expires (ISO 8601) |
| `data.storageProvider` | string | Storage provider used (`firebase`, `s3`, `supabase`) |
| `data.processingTimeMs` | number | Time to generate the PDF in milliseconds |
| `data.generationMethod` | string | `html` or `template` |
| `data.templateUsed` | object | Template info if using a template (`id`, `name`) |
| `usage.remaining` | number | Total credits remaining |
| `usage.quotaUsed` | number | Quota used this billing period |
| `usage.quotaLimit` | number | Monthly quota limit |
### External Storage Response
When using external storage (S3 or Supabase), additional fields are included:
```json theme={null}
{
"success": true,
"data": {
"fileId": "file_1734012345_xyz789",
"url": "https://your-bucket.s3.amazonaws.com/pdfs/document.pdf?...",
"storageProvider": "s3",
"externalCopies": [
{
"provider": "s3",
"name": "Production S3",
"url": "https://your-bucket.s3.amazonaws.com/pdfs/document.pdf",
"expiresAt": "2024-12-22T10:30:00.000Z"
}
]
}
}
```
## Error Codes
| Code | Status | Description |
| ---------------------------- | ------ | --------------------------------------------- |
| `VALIDATION_ERROR` | 400 | Invalid request parameters |
| `INVALID_API_KEY` | 401 | API key missing or invalid |
| `TEMPLATE_NOT_FOUND` | 404 | Template ID doesn't exist or isn't accessible |
| `WORKSPACE_NOT_FOUND` | 404 | Workspace associated with API key not found |
| `TEMPLATE_COMPILATION_ERROR` | 400 | Handlebars syntax error in template |
| `REQUEST_TIMEOUT` | 408 | PDF generation exceeded timeout limit |
| `FILE_TOO_LARGE` | 413 | Generated PDF exceeds size limit |
| `NO_CREDITS_AVAILABLE` | 429 | No quota or credits remaining |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `PDF_GENERATION_FAILED` | 502 | Internal error generating PDF |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
### Error Response Format
```json theme={null}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Either htmlContent or templateId is required",
"details": [
"Either htmlContent or templateId is required"
],
"requestId": "req_1734012345_abc123",
"timestamp": "2024-12-15T10:30:00.000Z"
}
}
```
## Examples
### Minimal Request
```bash theme={null}
curl -X POST https://api.fileloom.io/v1/pdf/generate \
-H "X-API-Key: fl_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"htmlContent": "Hello World
"
}'
```
### With Dynamic Data
```bash theme={null}
curl -X POST https://api.fileloom.io/v1/pdf/generate \
-H "X-API-Key: fl_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"htmlContent": "Invoice #{{number}}
Amount: {{currency amount \"USD\"}}
",
"templateData": {
"number": "INV-001",
"amount": 299.99
}
}'
```
### Full Options
```bash theme={null}
curl -X POST https://api.fileloom.io/v1/pdf/generate \
-H "X-API-Key: fl_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"htmlContent": "Report
Content here
",
"filename": "quarterly-report",
"options": {
"format": "Letter",
"orientation": "landscape",
"margin": {
"top": 20,
"right": 15,
"bottom": 20,
"left": 15
},
"printBackground": true,
"header": {
"enabled": true,
"height": 15,
"content": "Quarterly Report - Q4 2024
"
},
"footer": {
"enabled": true,
"height": 10,
"content": "Page of
"
}
}
}'
```
### Using a Template
```bash theme={null}
curl -X POST https://api.fileloom.io/v1/pdf/generate \
-H "X-API-Key: fl_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"templateId": "tpl_invoice_standard",
"templateData": {
"invoiceNumber": "INV-2024-0042",
"date": "2024-12-15",
"dueDate": "2025-01-14",
"customer": {
"name": "Acme Corporation",
"address": "123 Business Ave",
"city": "San Francisco",
"state": "CA",
"zip": "94102"
},
"items": [
{"description": "Consulting Services", "hours": 40, "rate": 150},
{"description": "Development", "hours": 80, "rate": 125}
],
"subtotal": 16000,
"tax": 1440,
"total": 17440
}
}'
```