Merge PDFs

Merges multiple PDF files into a single PDF. Files are combined in alphanumeric order (numbers first, then alphabetical).

Basics

POST/forms/pdfengines/merge

Headers

Gotenberg-Output-Filenamestring

The filename of the resulting file - Gotenberg automatically appends the file extension. Defaults to a random UUID filename.

Gotenberg-Tracestring

A custom request ID to identify the request in the logs; overrides the default UUID.

Form Files

filesfile[]required

PDF files to merge.

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
-o my.pdf

Responses

200

The merged PDF file.

Content-Disposition: attachment; filename={output-filename.pdf}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}

400

The request had one ore more invalid form fields.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}

503

The request did not complete within the configured maximum duration.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: Service Unavailable

Structure & Metadata

Metadata (PDF Engines)

Inject XMP metadata (Author, Title, Copyright, Keywords, etc.) into the PDF as a JSON object.

Not all tags are writable. Gotenberg uses ExifTool under the hood. See the XMP Tag Name documentation for valid keys. Writing metadata usually breaks PDF/A compliance.

Form Fields

metadatajson

Writes metadata (Author, Title, etc.).

Default:None

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form 'metadata={"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreationDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"}' \
-o my.pdf

Bookmarks (PDF Engines)

Form Fields

bookmarksjson

Bookmarks to write (JSON). A list applies to the final merged PDF. A map of filename→bookmarks shifts page indexes per file before merging.

Default:None

autoIndexBookmarksboolean

Extracts existing bookmarks from input files and offsets their page numbers based on their position in the merged document.

Default:false

Use autoIndexBookmarks to automatically extract existing bookmarks and offset their page numbers based on position in the merged document.

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form autoIndexBookmarks=true \
-o my.pdf

You can also provide custom bookmarks with the bookmarks form field. When provided as a list, it is applied directly to the final merged PDF. When provided as a map of filename to bookmarks, page indexes are shifted per file before merging.

Both options work together. When autoIndexBookmarks is enabled, Gotenberg respects your custom mappings for specific files while automatically recalculating indexes for the others.

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form autoIndexBookmarks=true \
--form 'bookmarks={"1_pdf.pdf":[{"title":"Introduction","page":1,"children":[]}],"2_pdf.pdf":[{"title":"Appendix","page":1,"children":[]}]}' \
-o my.pdf

Attachments (PDF Engines)

Attach external files directly inside the PDF container. Commonly used for e-invoicing standards like ZUGFeRD / Factur-X, which require a machine-readable XML invoice as an attachment.

Form Files

embedsfile[]

Embeds files into the PDF.

Default:None

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form embeds=@invoice.xml \
--form embeds=@logo.png \
-o my.pdf

Flatten (PDF Engines)

Merges all interactive form fields (text inputs, checkboxes, etc.) into the page content, making the PDF non-editable.

Form Fields

flattenboolean

Converts form fields into static content, preventing further editing.

Default:false

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form flatten=true \
-o my.pdf

Watermark (PDF Engines)

Adds a watermark behind the content of each page during post-processing. Sources: text, image, or pdf.

The watermarkOptions form field accepts a JSON object whose keys depend on the configured PDF Engine:

Engine	Syntax Reference
pdfcpu (Default)	See pdfcpu watermark documentation
pdftk	See pdftk documentation

Available keys include font, points (font size), color, rotation, opacity, scale, offset, and more. Example:

{
  "font": "Helvetica",
  "points": 48,
  "color": "#808080",
  "rotation": 45,
  "opacity": 0.15
}

Check the PDF Engines Configuration to see which engine is active.

Form Fields

watermarkSourceenum

The watermark source type. Options: 'text', 'image', 'pdf'.

watermarkExpressionstring

The watermark content. For 'text', the string to render. For 'image' or 'pdf', the filename of the uploaded watermark file.

watermarkPagesstring

Page ranges to watermark (e.g., '1-3', '5'). Empty means all pages.

watermarkOptionsjson

Advanced options in JSON format (e.g., font, color, rotation, opacity, scaling).

Form Files

watermarkfile

An image or PDF file used as watermark source (required when watermarkSource is 'image' or 'pdf').

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form watermarkSource=text \
--form watermarkExpression=CONFIDENTIAL \
--form 'watermarkOptions={"opacity":0.25,"rotation":45}' \
-o my.pdf

Stamp (PDF Engines)

Adds a stamp on top of the content of each page during post-processing. Sources: text, image, or pdf.

The stampOptions form field accepts a JSON object whose keys depend on the configured PDF Engine:

Engine	Syntax Reference
pdfcpu (Default)	See pdfcpu stamp documentation
pdftk	See pdftk documentation

Available keys include font, points (font size), color, rotation, opacity, scale, offset, and more. Example:

{
  "font": "Helvetica",
  "points": 24,
  "color": "#008000",
  "rotation": 0,
  "opacity": 0.6
}

Check the PDF Engines Configuration to see which engine is active.

Form Fields

stampSourceenum

The stamp source type. Options: 'text', 'image', 'pdf'.

stampExpressionstring

The stamp content. For 'text', the string to render. For 'image' or 'pdf', the filename of the uploaded stamp file.

stampPagesstring

Page ranges to stamp (e.g., '1-3', '5'). Empty means all pages.

stampOptionsjson

Advanced options in JSON format (e.g., font, color, rotation, opacity, scaling).

Form Files

stampfile

An image or PDF file used as stamp source (required when stampSource is 'image' or 'pdf').

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form stampSource=text \
--form stampExpression=APPROVED \
--form 'stampOptions={"opacity":0.5,"rotation":0}' \
-o my.pdf

Rotate (PDF Engines)

Rotates pages by 90, 180, or 270 degrees during post-processing.

Form Fields

rotateAngleenum

The rotation angle. Options: '90', '180', '270'.

rotatePagesstring

Page ranges to rotate (e.g., '1-3', '5'). Empty means all pages.

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form rotateAngle=90 \
-o my.pdf

PDF/A & PDF/UA (PDF Engines)

Converts to PDF/A (archival) or PDF/UA (accessibility) during post-processing using LibreOffice. Slower than native conversion (requires a second pass).

PDF/A and encryption are mutually exclusive: requesting both returns 400 Bad Request. PDF/A-1b and PDF/A-2b don't support file attachments; use PDF/A-3b if you need both.

When PDF/A runs alongside other post-processing, LibreOffice overwrites CreateDate, ModDate, and Keywords. Other metadata fields are preserved.

Form Fields

pdfaenum

Converts to a specific PDF/A archival standard. Options: 'PDF/A-1b', 'PDF/A-2b', 'PDF/A-3b'.

pdfuaboolean

Enables PDF/UA (Universal Accessibility) compliance.

Default:false

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form pdfa=PDF/A-1b \
--form pdfua=true \
-o my.pdf

Encryption (PDF Engines)

Set passwords to control PDF access. The user password is required to open the PDF; the owner password controls permissions (printing, copying, editing).

Encryption strength (e.g., AES-256) depends on the active PDF Engine. See PDF Engines Configuration.

Form Fields

userPasswordstring

The password required to open the PDF.

Default:None

ownerPasswordstring

The password required to change permissions or edit the PDF.

Default:None

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.pdf

Sponsors

Powered by

❤️ Become a sponsor