Troubleshooting
If requests fail, run zero doctor check-connector --env-name PDFORGE_API_KEY or zero doctor check-connector --url https://api.pdfnoodle.com/v1/pdf/sync --method POST
How to Use
All examples below assume you have PDFORGE_API_KEY set.
Base URL: https://api.pdfnoodle.com/v1
1. Generate PDF from Template (Sync)
Generate a PDF using a pre-built template with dynamic data.
Write to /tmp/pdforge_request.json:
{
"templateId": "your-template-id",
"data": {
"name": "John Doe",
"date": "2025-01-15",
"items": [
{"description": "Item 1", "price": 100},
{"description": "Item 2", "price": 200}
]
}
}
Then run:
curl -s -X POST "https://api.pdfnoodle.com/v1/pdf/sync" --header "Authorization: Bearer $PDFORGE_API_KEY" --header "Content-Type: application/json" -d @/tmp/pdforge_request.json
Response:
{
"signedUrl": "https://storage.googleapis.com/...",
"executionTime": 1234
}
The signedUrl is a temporary URL (expires in 1 hour) to download the generated PDF.
2. Generate PDF from Template (Async)
For batch processing, use the async endpoint with a webhook.
Write to /tmp/pdforge_request.json:
{
"templateId": "your-template-id",
"webhook": "https://your-server.com/webhook",
"data": {
"name": "Jane Doe",
"amount": 500
}
}
Then run:
curl -s -X POST "https://api.pdfnoodle.com/v1/pdf/async" --header "Authorization: Bearer $PDFORGE_API_KEY" --header "Content-Type: application/json" -d @/tmp/pdforge_request.json
Response:
{
"requestId": "abc123"
}
The webhook will receive the signedUrl when generation is complete.
3. Convert HTML to PDF (Sync)
Convert raw HTML directly to PDF without a template.
Write to /tmp/pdforge_request.json:
{
"html": "<html><body><h1>Hello World</h1><p>This is a PDF generated from HTML.</p></body></html>"
}
Then run:
curl -s -X POST "https://api.pdfnoodle.com/v1/html-to-pdf/sync" --header "Authorization: Bearer $PDFORGE_API_KEY" --header "Content-Type: application/json" -d @/tmp/pdforge_request.json
4. Convert HTML to PDF with Styling
Include CSS for styled PDFs.
Write to /tmp/pdforge_request.json:
{
"html": "<html><head><style>body { font-family: Arial; } h1 { color: #333; } .invoice { border: 1px solid #ddd; padding: 20px; }</style></head><body><div class=\"invoice\"><h1>Invoice #001</h1><p>Amount: $500</p></div></body></html>"
}
Then run:
curl -s -X POST "https://api.pdfnoodle.com/v1/html-to-pdf/sync" --header "Authorization: Bearer $PDFORGE_API_KEY" --header "Content-Type: application/json" -d @/tmp/pdforge_request.json
5. Generate PNG Instead of PDF
Set convertToImage to true to get a PNG.
Write to /tmp/pdforge_request.json:
{
"html": "<html><body><h1>Image Export</h1></body></html>",
"convertToImage": true
}
Then run:
curl -s -X POST "https://api.pdfnoodle.com/v1/html-to-pdf/sync" --header "Authorization: Bearer $PDFORGE_API_KEY" --header "Content-Type: application/json" -d @/tmp/pdforge_request.json
6. Download Generated PDF
After getting the signedUrl, download the PDF:
Replace <your-signed-url> with the actual signed URL from the previous response:
curl -s -o output.pdf "https://storage.googleapis.com/<your-signed-url>"
Request Parameters
Template Endpoint Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| templateId | string | Yes | Template ID from dashboard |
| data | object | Yes | Variables for the template |
| webhook | string | Async only | Webhook URL for delivery |
| convertToImage | boolean | No | Return PNG instead of PDF |
| metadata | object | No | PDF metadata (title, author, etc.) |
| hasCover | boolean | No | Hide header/footer on first page |
| debug | boolean | No | Enable debug mode |
HTML Endpoint Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| html | string | Yes | HTML content to convert |
| convertToImage | boolean | No | Return PNG instead of PDF |
| metadata | object | No | PDF metadata settings |
| pdfParams | object | No | PDF generation options |
Metadata Object
{
"metadata": {
"title": "Invoice #001",
"author": "Company Name",
"subject": "Monthly Invoice",
"keywords": ["invoice", "payment"]
}
}
Guidelines
- Use templates for reusable documents: Create templates in the dashboard for invoices, reports, etc.
- Use HTML endpoint for one-off documents: When you don't need a reusable template
- Use async for batch processing: Async endpoint is better for generating many PDFs
- Download promptly: Signed URLs expire in 1 hour
- Include CSS inline: For HTML to PDF, include all styles in the HTML