This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/document-engine/editor/watermark.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Add watermarks to PDF server-side | Nutrient Document Engine

Add watermarks to PDFs

Markdown version of this page, suitable for AI agents and automation

Watermarking embeds visual elements into a document’s pages — usually to mark ownership, add a disclaimer, or discourage redistribution. A watermark can be transparent, opaque, or invisible. Flattening it into the page content makes it a permanent part of the document.

Document Engine enables you to watermark documents using the watermark action.

Requirements

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Add a watermark

Set up the watermark action with the required options, which define where the watermark sits and how it looks. The options cover both text and image watermarks, and they hide the lower-level annotation details.

The action creates and flattens the watermark annotations itself, so there are no annotations to manage by hand.

For more control, create the annotations per page with the PDF Annotations API and flatten them with the Flatten PDF API.

Watermarking a file on disk

To add a TOP SECRET text watermark, send a request to the /api/build endpoint. Attach the document file and put the watermark instructions in the instructions JSON payload:

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "actions": [
        {
          "type": "watermark",
          "text": "TOP SECRET",
          "width": 100,
          "height": 200
        },
        {
          "type": "flatten"
        }
      ]
    }
  ]
}' \
  -o result.pdf

The next example works on a four-page document. It puts an image watermark on the first page and a text annotation on the last. Flattening both into the output PDF means the watermark can’t be erased:

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F image-local=@/path/to/image-watermark.png \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": "image-local",
        "width": 100
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 1,
        "end": 2
      }
    },
    {
      "file": "document",
      "pages": {
        "start": 3,
        "end": 3
      },
      "actions": {
        "type": "watermark",
        "text": "TOP SECRET",
        "width": 100,
        "height": 200
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}' \
  -o result.pdf

Watermarking a file from URL

URLs work anywhere a local file path does — for the documents in the file parts and for the images used as watermarks.

The next example adds an image annotation to every page and flattens it, so the watermark can’t be erased. The request to the /api/build endpoint attaches two URLs: one for the input file, one for the image.

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      },
      "pages": {
        "start": 0,
        "end": 0
      },
      "actions": {
        "type": "watermark",
        "image": {
          "url": "https://image-url.com/path-to-image-on-internet.png"
        },
        "width": 100
      }
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}' \
  -o result.pdf

A URL for an image annotation has to carry the image’s MIME type in the URL itself. Above, that MIME type is png.

Exporting watermarks added to a PDF document

A GET request to Document Engine’s /api/documents/:document_id/document.json endpoint exports a document’s current annotations, watermarks included, as an Instant JSON file. For more information, refer to the import and export Instant JSON PDF annotation data guide.