More than one document / POST /v1/pdf/batch
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
What it is for
For the moment a billing run closes and four hundred invoices have to exist. Sending four hundred separate requests works and spends four hundred round trips on it. A batch sends one request, renders each item, and returns a results array where each entry says what happened to that item.
The request
Sent to POST /v1/pdf/batch. Everything else on this page is what happens around it.
curl -X POST https://api.pdfpipe.xyz/v1/pdf/batch \
-H "Authorization: Bearer $PDFPIPE_KEY" \
-H "Content-Type: application/json" \
-d '{
"options": { "format": "A4", "margin": "16mm" },
"requests": [
{ "html": "<h1>Invoice 1</h1>", "filename": "inv-1.pdf" },
{ "html": "<h1>Invoice 2</h1>", "filename": "inv-2.pdf" }
],
"webhook_url": "https://your-app.example/hooks/batch",
"webhook_secret": "a-secret-of-at-least-16-chars"
}'The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- Items per call depend on the plan: 10 on Starter, 50 on Growth, 100 on Scale, 250 on Business.
- Shared options apply to every item and per-item options override them.
- Every item is stored, so batch requires document storage and inherits your plan's retention.
- A webhook_secret must be at least 16 characters, and the webhook_url is checked against the same private-address guard as a URL render.
- Each item consumes one document from your quota. A batch of fifty is fifty documents.
What failure looks like
The call returns 200 even when some items fail, and the failures are in the results array. That is deliberate: a batch where item 37 has a broken template should not throw away the other items. It does mean a caller that checks only the HTTP status will silently lose documents, so the results array has to be read.
Plan availability
Not available on the free plan. Attempting it returns 403 with plan_required and a message naming the smallest plan that includes it.
When this is the wrong tool
When the documents are produced one at a time by user actions rather than by a scheduled run. Batching a queue that arrives continuously means holding documents back to group them, which adds latency to every one of them to save round trips nobody was counting.
Frequently asked
Is batch rendering available on the free plan?
Not available on the free plan. Attempting it returns 403 with plan_required and a message naming the smallest plan that includes it.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Merge several PDFs into one over an API
Combines between two and twenty PDFs into a single file, taking each one as a stored document id, a public URL, or base64 in the request.
Store generated PDFs and fetch them later
Keeps a copy of the rendered document so it can be fetched again later, with a retention period that depends on the plan.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Check API usage and remaining document quota
How many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.