Skip to main content

Split PDFs

Splits one or more PDF files.

This endpoint allows you to extract specific pages or split the document into intervals. The result can be a ZIP archive of individual files or a unified PDF containing the extracted pages.

Syntax Validation

When splitMode is set to pages, Gotenberg does not validate the splitSpan syntax.

The value is passed directly to the underlying PDF Engine, and the valid syntax depends on which engine you have configured:

EngineSyntax Reference
pdfcpu (Default)See pdfcpu /trim documentation
QPDFSee QPDF page-ranges documentation
PDFtkSee PDFtk cat operation

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

Basics​

POST/forms/pdfengines/split
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 Fields
splitModeenumrequired
Activates the splitting engine. Options: 'intervals' or 'pages'.
splitSpanstringrequired
The rule for splitting. If mode is 'intervals', defines the chunk size (e.g. '2'). If mode is 'pages', defines the page ranges.
splitUnifyboolean
Only for 'pages' mode. If true, puts all extracted pages from a PDF into a single PDF file. If false, creates a separate file for each range.
Default:false
Form Files
filesfile[]required
PDF files to split.
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
-o my.zip
Responses
The split PDF files (ZIP) or unified PDF.
Content-Disposition: attachment; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}

Structure & Metadata​

Form Fields
metadatajson
Writes metadata (Author, Title, etc.).
Default:None
flattenboolean
Converts form fields into static content, preventing further editing.
Default:false
Form Files
embedsfile[]
Embeds files into the PDF.
Default:None

Metadata (PDF Engines)​

Use the metadata form field to inject XMP metadata into the generated PDF. This allows you to set properties like Author, Title, Copyright, and Keywords by passing a JSON-formatted object.

Valid Keys

Not all metadata tags are writable. Gotenberg relies on ExifTool for this operation. See the XMP Tag Name documentation for a list of potential keys.

Compliance Warning

Writing metadata involves modifying the PDF structure and usually breaks PDF/A compliance.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--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.zip

Attachments (PDF Engines)​

Use the embeds form field to attach external files directly inside the PDF container.

Common Use Case: This is essential for e-invoicing standards like ZUGFeRD / Factur-X, which require a human-readable PDF to carry a machine-readable XML invoice as an attachment.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form embeds=@invoice.xml \
--form embeds=@logo.png \
-o my.zip

Flatten (PDF Engines)​

Use the flatten form field to make the PDF non-interactive.

This process merges all interactive form fields (text inputs, checkboxes, etc.) directly into the page content. The resulting PDF cannot be modified by the end-user.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form flatten=true \
-o my.zip

PDF/A & PDF/UA (PDF Engines)​

Use the pdfa and pdfua form fields to convert the result into a standardized PDF format during post-processing.

  • Process: Gotenberg generates the result, then re-processes it using LibreOffice (the only engine supporting these standards).
  • Performance: Slower (requires a second conversion pass).
  • Result: A compliant PDF/A (Archival) or PDF/UA (Universal Accessibility) document.
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/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.zip

Encryption (PDF Engines)​

Secure your PDF by setting passwords that control access and permissions.

  • User Password: Required to open and view the PDF.
  • Owner Password: Required to modify permissions (e.g., printing, copying text, extracting pages).
PDF Engine Dependency

The encryption strength (e.g., AES-256) depends on the configured PDF Engine (QPDF, pdfcpu, or PDFtk).

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

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/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.zip
TheCodingMachinepdfme
Powered by
DockerJetBrains
❤️ Become a sponsor