POST /api/pdf/batch
100 PDFs in a single API call
POST returns immediately with a batch_id while the job queue runs items in parallel. Detect completion via polling or the batch.completed webhook event. Ideal for monthly invoice runs, ticket issuance, and bulk reports.
Key points
1
Instant response, async work
POST returns 201 with a batch_id right away. Clients don't wait around or risk request timeouts and can move on to other work.
2
Two ways to track status
Either poll GET /api/pdf/batch/ or subscribe to the batch.completed webhook event — pick whichever fits your architecture.
3
Failures retry automatically
Each item runs with tries=2. Failed items are returned with error_message so you can selectively re-submit just those.
With this feature vs. without
| Use the batch API | Call one at a time | |
|---|---|---|
| 100-item wall time | 1 API call, 201 instantly | 100 sync calls, several minutes total |
| Client-side control | Hold a batch_id, check later | Manage parallelism, ordering, retries yourself |
| On error | Re-run only the failed items | Plan for partial-failure recovery yourself |
| Best fit | 10+ items, especially nightly runs | 1–few real-time generations |
How it looks in code
// Submit up to 100 PDFs in one call → 201 Created with batch_id
const res = await fetch("/api/pdf/batch", {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}` },
body: JSON.stringify({
items: orders.map(o => ({
type: "html",
html: renderInvoice(o),
expiration_hours: 72,
})),
}),
});
const { data: { batch_id } } = await res.json();
// Either poll for status...
const status = await fetch(`/api/pdf/batch/${batch_id}`, {
headers: { "Authorization": `Bearer ${API_KEY}` },
}).then(r => r.json());
// ...or subscribe to the batch.completed webhook event.