Merging PDFs Without Flattening Everything Into Images
A proper PDF merge concatenates page streams: fonts, vectors, and bookmarks stay intact. Rasterizing every page into images is a different, lossier job.

“Merge these five PDFs” can mean two pipelines. One concatenates existing page objects into a single file. The other prints every page to a bitmap and packs the images into a new PDF. Both produce one attachment. Only the first keeps selectable text and sharp vectors.
What a structural merge does
On PDF123, Merge combines two or more PDFs by joining each file’s page objects. The server path runs qpdf with an empty base and --pages over the inputs, the page-selection form the qpdf manual documents for merging pages from several files: page streams move as pages, not as screenshots. Embedded fonts and vectors travel with those pages, but bookmarks do not: the manual says qpdf takes document-level information such as outlines from the primary input, and an empty base has none. Nothing in that path rasterizes a page into an image, so a born-digital contract can still search and copy after the join.
Upload order is output order by default. The HTTP form accepts repeated fileInput parts in one request; batch size is bounded by upload limits, not by a hard two-file cap. Optional sortType=byFileName reorders inputs by filename before the join. Bookmarks from the sources are not carried into the merged file (in a test run, two inputs with one bookmark each produced a merged file with none), so keep the originals if you need their outlines.
A single-file upload is a no-op pass-through of that PDF. Two or more files become one merged.pdf whose pages are the concatenation of the inputs in the chosen order. The same op id is what OpenAPI, MCP, and pdfx merge expose, so a script and a browser click do not secretly disagree about “merge.”
When people accidentally rasterize
Some “combine” workflows export to images first (fax gateways, scan apps, print-to-PDF at screen resolution) or flatten annotations into bitmaps before joining. File size jumps, OCR may be required again, and zoom shows pixel edges.
Prefer a stream merge when sources are already digital PDFs. Prefer OCR only when the inputs are scans without usable text, and remember OCR here returns Markdown (text/markdown) by default; its searchable-PDF output is rebuilt from 300 dpi page images with a hidden text layer, not merged from the original pages. Rasterizing then OCR-ing is a different product path from merging born-digital files.
If you need images of pages, that is a convert job (PDF to images), not a merge. Mixing those intents is how “merged” files become multi-megabyte photo albums of documents. Compress after a structural merge can still shrink streams (Compress); it does not undo a raster flatten you already baked in.
What merge does not promise
Merge does not normalize page sizes, unify fonts across files, or rebuild a table of contents from scratch. It does not decrypt encrypted inputs for you; unlock first if the source is password-protected. It does not replace a portfolio/package container format that some court portals expect; it produces one ordinary multi-page PDF.
Those limits are the same whether you use the browser, REST, MCP, or pdfx. The op is intentionally narrow so the output stays predictable for automation. If you need ordered multi-step work (merge, then watermark, then compress), use POST /api/v1/pipeline with an ordered steps list instead of inventing a second “smart merge” flag.
How to run it
Merge PDFs in the browser, or POST /api/v1/general/merge-pdfs with repeated fileInput parts (Developers). From a shell:
pdfx merge a.pdf b.pdf -o merged.pdf
Or pin an explicit base and key, for a self-hosted or alternative server:
pdfx --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Anonymous catalog calls need no key on the public site; keys matter for stable automation identity and for gated self-hosted servers. For the same op through curl and MCP as well, see Same operation, four clients.