Watermark PDFs

Adds a watermark behind the content of each page of one or more PDF files. Use text for a simple label, image to tile an uploaded image, or pdf to place a full-page PDF underneath.

See the PDF Engines module configuration for engine selection flags.

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 module configuration to see which engine is active.

Basics

POST/forms/pdfengines/watermark

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

watermarkSourceenumrequired

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

watermarkExpressionstringrequired

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

filesfile[]required

PDF files to watermark.

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/watermark \
--form files=@/path/to/file.pdf \
--form watermarkSource=text \
--form watermarkExpression=CONFIDENTIAL \
--form 'watermarkOptions={"opacity":0.25,"rotation":45}' \
-o my.pdf

Responses

200

The watermarked PDF file. Multiple input files produce a ZIP archive.

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

400

The request had one or 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: {error}

Multiple Watermarks

Repeat the watermark form fields to apply several watermarks in one request. Gotenberg reads watermarkSource, watermarkExpression, watermarkPages, and watermarkOptions as parallel lists and applies each watermark in order. A single occurrence of each field is the single-watermark case above.

Each image or pdf watermark consumes the uploaded watermark files in order; text watermarks take none.

curl \
--request POST http://localhost:3000/forms/pdfengines/watermark \
--form files=@/path/to/file.pdf \
--form watermarkSource=text --form watermarkExpression=DRAFT \
--form watermarkSource=image --form watermark=@/path/to/logo.png \
-o my.pdf

What's Next?

Overlay text or images with Stamp, or fix page orientation with Rotate.