Stamp PDFs

Adds a stamp on top of the content of each page of one or more PDF files. Use text for a simple label, image to overlay an uploaded image, or pdf to place a full-page PDF on top.

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.

POST/forms/pdfengines/stamp

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

stampSourceenumrequired

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

stampExpressionstringrequired

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

filesfile[]required

PDF files to stamp.

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/stamp \
--form files=@/path/to/file.pdf \
--form stampSource=text \
--form stampExpression=APPROVED \
--form 'stampOptions={"opacity":0.5,"rotation":0}' \
-o my.pdf

Responses

The stamped PDF file.

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

The request had one ore more invalid form fields.

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

The request did not complete within the configured maximum duration.

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