Add Watermark API

Add a text or image watermark to a PDF.

Feature

The ComPDF Self-hosted accepts files and a request JSON string through multipart/form-data, forwards the parameters to the private PDF SDK, and streams the result file back on success.

Synchronous Request

Item	Value
Authentication	x-api-key: your_api_key_here
Request URL	POST http://localhost:8080/api/v1/process/pdf/watermark/add
Content type	multipart/form-data
Success response	Result file stream

Request Parameters

Parameter	Type	Description	Required
file	File	Source PDF file.	Yes
imageFile	File	Image watermark file. Required only when request.type is image.	No
request	String	JSON string containing the PDF SDK parameters below. If omitted, remaining non-file form-data fields are forwarded as the request object.	No

Request Object Parameters

Put the following fields in the request JSON string.

Parameter	Type	Purpose
type	String or Integer	PDF to JSON content scope used by the ComPDF Web. 0 = text, 1 = table, 2 = all.
text	String	Watermark text.
fontSize	Number	Text watermark font size.
fontColor	String	Text color, for example #D32F2F.
opacity	Number	Watermark opacity. Common range: 0 to 1.
rotation	Number	Watermark rotation angle in degrees.
horizalign	String	Horizontal alignment such as left, center, or right.
vertalign	String	Vertical alignment such as top, center, or bottom.
horizOffset	Number	Horizontal offset in points.
vertOffset	Number	Vertical offset in points.
horizontalSpacing	Number	Horizontal spacing for repeated watermarks.
verticalSpacing	Number	Vertical spacing for repeated watermarks.
fullScreen	Boolean	Whether to tile the watermark across the page.
pages	String or Number[]	Pages to process. Examples: 1, 1,3-5, [1,3,4,5], or all when supported.
password	String	Source PDF open password. Some routes remove it before forwarding when the SDK endpoint does not accept it directly.
outputFileName	String	Optional output filename. When present, it is used as the preferred download filename.

Request Example

curl -X POST "http://localhost:8080/api/v1/process/pdf/watermark/add" \
  -H "x-api-key: your_api_key_here" \
  -F "[email protected]" \
  -F 'request={"type":"text","text":"ComPDF","fontSize":"","fontColor":"","opacity":0.3}'

Response

On success, the API returns the processed file stream with Content-Type and Content-Disposition headers. On failure, the ComPDF Self-hosted returns a normalized error JSON response.