Run stages

Runs a list of stages on the PDFs you upload, in order.

POST/forms/pdf/pipe

Form data

filesfile[]required

The PDFs, and the files the stages name, such as a stamp's image.

stagesjsonrequired

The stages to run, in order, such as [{"op":"merge"},{"op":"optimize"}].

archivesfile[]

ZIP files Gotenberg unpacks: each entry counts as a file uploaded under files.

downloadFromjson

URLs Gotenberg downloads first, as if you had uploaded the files. Each entry takes a url, and optionally extraHttpHeaders.

Response

The PDF, or a ZIP when several PDFs come out: several uploads without a merge, or a split.

The route also takes the headers. An error answers a status and a message: see Errors.

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form 'stages=[
    { "op": "select", "pages": "1-2" },
    { "op": "stamp-text", "text": "DRAFT", "x": 72, "y": 72, "fontSize": 24 },
    { "op": "optimize" }
  ]' \
  -o report.pdf

How stages work

• Each stage works on what the previous one produced, so its page numbers count from that PDF.
• The stages take the PDFs in the alphanumeric order of their names.
• A stage names the files it needs, such as an image to stamp or a certificate, by their uploaded names. Upload them under files: they don't count as PDFs to process.
• stages works on this route and on the Chromium and LibreOffice conversions, where the stages run on the converted PDFs. The screenshot routes, the stages' own routes and the read routes answer 400 to it.
• Each stage also has its own route, /forms/pdf/<op>, which takes its options as form fields, with a list or an object as JSON.

Every stage

Stage	What it does
merge	Appends the PDFs into one, in the alphanumeric order of their names. The result takes the name of the first.
split	Cuts each PDF into several, which come back in a ZIP: report_0.pdf, report_1.pdf… The stages after it run on each part.
select	Keeps the pages you list, in the order you list them.
delete	Removes the pages you list.
insert	Inserts the pages of another uploaded PDF.
rotate	Sets the rotation of pages. Viewers turn them clockwise.
stamp-text	Draws a line of text over pages.
stamp-image	Draws an uploaded PNG or JPEG image over pages.
stamp-pdf	Draws a page of another uploaded PDF over pages: a letterhead, a seal.
set-metadata	Writes the document information. A field you leave out keeps its value.
set-bookmarks	Replaces the bookmarks, the outline viewers show beside the pages.
set-form	Fills form fields.
flatten-form	Burns the form fields into the pages, which can then no longer be edited. A value without a stored appearance is drawn, with an installed font for text outside Western European.
flatten-transparency	Replaces transparent content with opaque content, for printers and archival formats that don't support transparency.
convert-colors	Converts every color to one color space.
redact	Removes the content under each region from the file itself, not just from view. Nothing is drawn in its place.
autotag	Infers a structure tree for an untagged PDF, so screen readers can follow it. PDF/UA requires one.
attach	Embeds an uploaded file in the PDF.
detach	Removes an embedded file.
optimize	Rewrites the PDF to shrink it. Every option is on unless you turn it off. A signed PDF answers 400, and so does an encrypted one, unless the stages decrypt or encrypt it.
encrypt	Protects the PDF with passwords.
decrypt	Opens encrypted PDFs and removes their encryption.
remediate	Repairs the PDF until it conforms to a profile, or to a PDF/A profile and a PDF/UA one together. Gotenberg-Remediation-Residual counts the violations left: 0 means it conforms.
sign	Signs the PDF with a certificate you upload.
timestamp	Adds a document timestamp from an RFC 3161 timestamp authority: proof the PDF existed, unchanged, at that time.
render	Draws pages as images, which come back in a ZIP next to the PDF: report_1.png. /forms/pdf/render returns the images alone.

Order rules

Gotenberg checks the order of the stages before it runs any, and answers 400 with the rule a list breaks:

• decrypt comes first, and render last.
• A list has at most one remediate, one encrypt, one sign and one timestamp. One remediate takes a PDF/A profile and a PDF/UA one together.
• After remediate, only encrypt, optimize, sign, timestamp and render may follow.
• After encrypt, only optimize and render may follow.
• After sign or timestamp, only sign, timestamp and render may follow.
• encrypt doesn't combine with sign, timestamp, or a PDF/A or Factur-X remediate.
• decrypt doesn't combine with sign or timestamp: sign the decrypted PDF in a request of its own.

What each stage does to the file

A stage either rewrites the PDF whole or appends an update to it. A rewrite drops signatures, so on a signed PDF those stages answer 400:

The file	Stages
Rewritten, signatures refused	select, delete, insert, merge, split, encrypt, decrypt, flatten-form, redact, remediate, convert-colors, flatten-transparency, optimize
Updated, signatures kept	rotate, stamp-text, stamp-image, stamp-pdf, set-form, set-metadata, set-bookmarks, attach, detach, autotag, sign, timestamp
Unchanged	render, which makes images

Page selections

An option of type pages takes a page (3), a range (2-5), a list of both (1,3,5-7), or all, odd, even or last on their own. Pages count from 1, and a page past the end answers 400.