More than one document / POST /v1/pdf/merge
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.
What it is for
The common case is a covering document plus attachments: an invoice with its timesheets, a contract with its schedules, a claim with its receipts. Each part is generated separately, often by different code, and the reader wants one file.
The request
Sent to POST /v1/pdf/merge. Everything else on this page is what happens around it.
curl -X POST https://api.pdfpipe.xyz/v1/pdf/merge \
-H "Authorization: Bearer $PDFPIPE_KEY" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{ "document_id": "doc_..." },
{ "url": "https://example.com/appendix.pdf" },
{ "base64": "JVBERi0xLjQK..." }
],
"filename": "contract-with-schedules.pdf",
"store": true
}' \
--output merged.pdfThe actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- At least two documents and at most twenty, in one call. Fewer than two returns 400, and so does more than twenty.
- Order in the array is the order in the output.
- There is a single wall-clock budget of thirty seconds for every URL fetch in the request, across all documents and all redirect hops, so a caller passing twenty slow URLs cannot hold connections open indefinitely.
- Daily merge limits apply per key and vary by plan, from a couple of hundred to several thousand.
What failure looks like
A source that is not a valid PDF fails the whole merge rather than being skipped, because a merged document silently missing a schedule is worse than a merge that did not happen. A URL that is slow enough to exhaust the shared fetch budget fails for the same reason.
Plan availability
Not available on the free plan. Calling it there returns 403 with plan_required.
When this is the wrong tool
When the parts are all generated by you in the same run. Concatenating your own HTML into one document before rendering gives you continuous page numbering, a single table of contents and consistent margins, none of which survive a merge of separately rendered files.
Frequently asked
Is merge pdfs available on the free plan?
Not available on the free plan. Calling it there returns 403 with plan_required.
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.
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.
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.