Convert Endpoint
The /convert endpoint accepts HTML content, a URL, or a stored template and returns a signed URL to download the generated PDF.
Try It Out
Test the API directly from your browser:
Try it out
Sign in to manage your API keys, or paste one below.
{
"html": "<!DOCTYPE html>\n<html>\n<head>\n <style>\n body { font-family: system-ui, sans-serif; padding: 40px; }\n h1 { color: #1a1a1a; }\n </style>\n</head>\n<body>\n <h1>Hello from PDFShot!</h1>\n <p>This PDF was generated from HTML.</p>\n</body>\n</html>",
"options": {
"format": "A4",
"margin": "1in",
"landscape": false,
"printBackground": true
}
}Endpoint
POST https://convert.pdfshot.com/convert
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer YOUR_API_KEY | Yes |
Content-Type | application/json | Yes |
Request Body
You must provide exactly one input source: html, url, or templateId.
From HTML
{
"html": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>",
"options": {
"format": "A4"
}
}
From URL
{
"url": "https://pdfshot.com/demo/invoice",
"options": {
"format": "Letter"
}
}
From Template
Render a stored template with variable substitution:
{
"templateId": "550e8400-e29b-41d4-a716-446655440000",
"variables": {
"customerName": "Acme Corp",
"invoiceNumber": "INV-001",
"items": [
{ "name": "Widget Pro", "qty": 2, "price": 50.00 },
{ "name": "Service Fee", "qty": 1, "price": 25.00 }
]
},
"options": {
"format": "A4"
}
}
Templates are created in your Dashboard and use Handlebars syntax for variable substitution. See Templates Guide for more details.
Parameters
Input (choose one)
| Parameter | Type | Description |
|---|---|---|
html | string | HTML content to render. Max 10MB. |
url | string | HTTPS URL to render. Must be publicly accessible. |
templateId | string | UUID of a stored template. Create templates in your Dashboard. |
Template Variables
| Parameter | Type | Description |
|---|---|---|
variables | object | Key-value pairs for Handlebars variable substitution. Required when using templateId. |
Options (all optional)
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | "A4" | Page size: A4, Letter, Legal, Tabloid, or custom |
margin | string or object | "0" | Page margins |
landscape | boolean | false | Landscape orientation |
printBackground | boolean | false | Print CSS backgrounds |
pageRanges | string | all | Pages to include, e.g., "1-5" or "1,3,5" |
scale | number | 1.0 | Scale factor (0.1 to 2.0) |
headerTemplate | string | none | HTML header template |
footerTemplate | string | none | HTML footer template |
See Options Reference for detailed documentation.
Response
Success (200)
{
"success": true,
"url": "https://pdf.pdfshot.com/abc123...",
"expiresAt": "2025-01-01T13:00:00.000Z",
"fileSizeBytes": 45321,
"processingTimeMs": 2340
}
| Field | Type | Description |
|---|---|---|
success | boolean | Always true for successful responses |
url | string | Signed URL to download the PDF (valid for 1 hour) |
expiresAt | string | ISO 8601 timestamp when the URL expires |
fileSizeBytes | number | PDF file size in bytes |
processingTimeMs | number | Total render time in milliseconds |
Error (4xx/5xx)
{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "HTML content is required when url is not provided"
}
}
See Error Codes for all possible errors.
URL Security
When using the url parameter:
- Must use HTTPS (HTTP is rejected)
- Private IP addresses are blocked (localhost, 10.x.x.x, 192.168.x.x, etc.)
- AWS metadata endpoints are blocked
This prevents server-side request forgery (SSRF) attacks.
Size Limits
- Maximum HTML size: 10MB
- Maximum render time: 2 minutes (timeout)
Billing
Usage is billed by render time, not by request count.
- Free tier: 5 minutes/month
- After free tier: $0.20 per render minute
A typical single-page document renders in 1-3 seconds.