Inkspan › Guides › Merge PDF API

Merge PDF API

Combine multiple PDFs into one in a single request — useful for stitching cover pages, appendices, or batched documents together programmatically.

Send the files field once per document. The order of the parts is the order of the output.

Example

import requests

files = [
    ('files', open('first.pdf', 'rb')),
    ('files', open('second.pdf', 'rb')),
]

r = requests.post(
    'https://api.inkspan.dev/v1/pdf/merge',
    headers={'X-API-Key': 'ink_live_...'},
    files=files,
)
r.raise_for_status()
with open('merged.pdf', 'wb') as f:
    f.write(r.content)

Request parameters

Name	Type	Required	Description
`files`	file[]	yes	Two or more PDF files. Repeat the `files` field once per document — do not send an array in a single field.

Response

Returns a PDF as a binary stream with Content-Type: application/pdf and Content-Disposition: attachment; filename=merged.pdf. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

The field is repeated, not indexed. Send files twice rather than files[0] and files[1]; a single file returns a copy rather than an error.
Order is the order of the parts in your request, so control it client-side if it matters.
Page sizes are preserved per page. Merging A4 and Letter gives a mixed-size PDF rather than normalising either.
Password-protected inputs fail to parse. Decrypt before merging.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

Is there a free tier?

Yes — 100 documents a month, no card required. Usage-based plans start at $19/month when you outgrow it.

How do I authenticate?

Send your key in the X-API-Key header on every request.

Do failed requests count against my quota?

No. Only successful requests are metered.

Get a free API key →

Full guides for /v1/pdf/merge: cURL · Python · Node.js · all guides