Split PDFs
Splits one or more PDF files by extracting specific pages or splitting into intervals. Returns a ZIP archive of individual files or a unified PDF.
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:
| Engine | Syntax Reference |
|---|---|
| pdfcpu (Default) | See pdfcpu /trim documentation |
| QPDF | See QPDF page-ranges documentation |
| PDFtk | See PDFtk cat operation |
Check the PDF Engines Configuration to see which engine is active.
Basics
falsecurl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
-o my.zip
- 200
- 400
- 503
Content-Disposition: attachment; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}
Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}
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.
Nonecurl \
--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)
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.
Nonecurl \
--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)
Merges all interactive form fields (text inputs, checkboxes, etc.) into the page content, making the PDF non-editable.
falsecurl \
--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
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.
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form watermarkSource=text \
--form watermarkExpression=CONFIDENTIAL \
--form 'watermarkOptions={"opacity":0.25,"rotation":45}' \
-o my.zip
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.
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form stampSource=text \
--form stampExpression=APPROVED \
--form 'stampOptions={"opacity":0.5,"rotation":0}' \
-o my.zip
Rotate (PDF Engines)
Rotates pages by 90, 180, or 270 degrees during post-processing.
curl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form rotateAngle=90 \
-o my.zip
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.
falsecurl \
--request POST http://localhost:3000/forms/pdfengines/split \
--form files=@/path/to/file.pdf \
--form splitMode=intervals \
--form splitSpan=1 \
--form pdfa=PDF/A-1b \
--form pdfua=true \
-o my.zip
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.
NoneNonecurl \
--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
