--- title: "Add watermarks to PDF server-side | Nutrient Document Engine" canonical_url: "https://www.nutrient.io/guides/document-engine/editor/watermark/" md_url: "https://www.nutrient.io/guides/document-engine/editor/watermark.md" last_updated: "2026-05-23T00:08:18.039Z" description: "Learn how to add text and image watermarks to your documents using Document Engine’s API. Secure and professionalize your files with text and image watermarks from disk or URLs." --- # Add watermarks to PDFs Watermarking is the process of embedding visual elements into a document’s pages, typically to indicate ownership, add disclaimers, or discourage redistribution. While these watermarks may be transparent, opaque, or even invisible, they can ultimately be flattened into the page content and become a permanent part of the document. Document Engine enables you to watermark documents using the [`watermark` action](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API/Instructions-Schema). ## Requirements - Ensure [Document Engine is up and running](https://www.nutrient.io/sdk/document-engine/getting-started.md). - Send a [multipart POST request](https://www.baeldung.com/postman-form-data-raw-x-www-form-urlencoded) with [instructions](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) to Document Engine’s `/api/build` endpoint. For more information, refer to the [API reference](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) 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](https://www.nutrient.io/blog/a-brief-tour-of-multipart-requests/) blog post. ## Add a watermark Set up the [`watermark` action](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API/Instructions-Schema) with the required [options](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API/Instructions-Schema), which define the appearance and position of the watermark. These options support both text and image watermarks and abstract away the lower-level annotation details. The watermark action automatically handles the creation and flattening of watermark annotations, so you don’t need to manage annotations manually. Alternatively, if you need more control, you can manually create annotations for each page using the [PDF Annotations API](https://www.nutrient.io/api/pdf-annotations-api/) and then flatten them using the [Flatten PDF API](https://www.nutrient.io/api/flatten-pdf-api/). ## Watermarking a file on disk To add a **TOP SECRET** text watermark to a document, send a request to the [`/api/build` endpoint](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Document-Editing/operation/build-document), include the document file as an attachment, and provide watermark instructions in the `instructions` JSON payload, as demonstrated in the code snippet below: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token 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 ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="document"; filename="example-document.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "parts": [ { "file": "document", "actions": [ { "type": "watermark", "text": "TOP SECRET", "width": 100, "height": 200 }, { "type": "flatten" } ] } ] } --customboundary-- ``` The following example adds an image watermark to the first page of a four-page document and a text annotation to the last page of the same document before flattening the annotations on the final output PDF so that the watermark can’t be erased: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token 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 ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="document"; filename="example-document.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="image-local"; filename="image-watermark.png" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "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" } ] } --customboundary-- ``` ## Watermarking a file from URL Instead of paths to local files, you can use URLs to specify both the documents to be watermarked in the file parts and the images to use for image watermarks. The following example adds an image annotation to all pages of a document and flattens them so that the watermark can’t be erased. This request to the [`/api/build` endpoint](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Document-Editing/operation/build-document) attaches two URLs, which point to the input file and the image, respectively: ### SHELL ```shell curl -X POST http://localhost:5000/api/build \ -H "Authorization: Token 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 ``` ### HTTP ```http POST /api/build HTTP/1.1 Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token= --customboundary Content-Disposition: form-data; name="instructions" Content-Type: application/json { "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" } ] } --customboundary-- ``` When using a URL to specify the path for an image annotation, the MIME type of the image needs to be a part of the image’s URL. In the example above, the MIME type of the image is `png`. ## Exporting watermarks added to a PDF document You can export the current annotations (including watermarks) of a PDF document as an Instant JSON file through a `GET` request to Document Engine’s `/api/documents/:document_id/document.json` endpoint. For more information, refer to the [import and export Instant JSON PDF annotation data](https://www.nutrient.io/guides/document-engine/annotations/import-and-export/instant-json.md) guide. --- ## Related pages - [Architecture diagram](/guides/document-engine/editor/architecture-diagram.md) - [Document processing and editing server](/guides/document-engine/editor.md) - [Merge multiple PDF files](/guides/document-engine/editor/merge-or-combine.md) - [Changing PDF page numbers or labels](/guides/document-engine/editor/page-label.md) - [Add pages to PDFs](/guides/document-engine/editor/add-page.md) - [Password protect PDFs](/guides/document-engine/editor/password-pdfs.md)