Batch PDF generation API for queues and jobs
Generate many PDFs through queue-safe JSON Render or Template Render workflows while your system owns chunking, retries, idempotency, and storage.
/api/v1/template-render Render many PDFs from a queue or scheduled job by splitting work into safe requests, sending each document or template data item to gPdf, and storing or delivering the returned PDF in your own system.
When to use this API
- You need to generate invoices, statements, labels, or reports in a scheduled or event-driven batch.
- You have a stable template and can send multiple data items within endpoint limits.
- You need queue-friendly rendering without running browser workers.
- You can own deduplication, retries, and output storage.
What it does not replace
- You need gPdf to be your batch scheduler, queue, storage system, or idempotency ledger.
- You need published rate-limit headers or a server-side idempotency-key contract.
- You need one unbounded request to render every document in a campaign.
Which endpoint to call
/api/v1/template-render
Template Render is the default path for this workflow.
/api/v1/pdf/render
Use this when the workflow needs the related API path, template contract, or capabilities lookup.
Minimal request
POST /api/v1/template-render - small batch with two invoice data items.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
What gPdf handles
- PDF rendering for each JSON Render or Template Render request.
- Template Render data arrays within documented public limits.
- Fast stateless render responses suitable for queue workers.
- Shared request ID and error envelope behavior.
What your system owns
- Queue design, chunking, concurrency, retries, deduplication, and output storage.
- Business object selection, template choice, and delivery workflow.
- Backoff policy, alerting, and recovery after partial failure.
Production checklist
- Chunk work so each request stays within documented item and payload limits.
- Generate one X-Request-Id per request and map it to your job ID.
- Retry only network or 5xx failures with bounded exponential backoff.
- Do not retry 4xx validation failures without changing the payload.
- Store output PDFs or source data according to your retention policy.
Claim boundaries
- gPdf is the render API, not the queue or storage layer.
- The public API does not publish rate-limit headers or server-side idempotency keys today.
- Your system must make retries safe.
Batch generation is an integration pattern
Batch PDF generation is not a separate endpoint. It is the way your queue uses the public render APIs. Keep jobs small, observable, and retry-safe.
For repeated layouts, Template Render usually gives the cleanest contract. For programmatic documents with custom layouts, JSON Render remains available.
FAQ
- Does gPdf provide a batch job API?
- No separate batch scheduler is exposed. Use JSON Render or Template Render from your own queue or worker system.
- Can Template Render accept multiple data items?
- Yes, within the public endpoint limits. Split larger jobs across requests.
- Who owns retries?
- Your system owns retries, backoff, deduplication, and idempotency. gPdf echoes request IDs for traceability.
- Can I render many different layouts in one request?
- Use separate requests when layouts or template IDs differ. Keep each request simple and traceable.