Add Watermark to PDF

Endpoint #

POST https://pixlab.davix.dev/v1/pdf

Action #

action=watermark

Description #

The Add Watermark to PDF action applies a text watermark or image watermark to pages of a PDF document using the H2I engine (PixLab).

This action is part of the public /v1/pdf API surface. It accepts a source PDF and applies either watermark text or an uploaded watermark image to selected pages. The processed document is returned as a generated PDF output through a signed URL under the public PDF output path.

Common uses include:

• labeling documents such as draft or confidential copies
• applying branding or logo overlays
• identifying ownership or internal review state
• adding visible page overlays to selected pages

Request Format #

Requests to /v1/pdf must use:

• Content-Type: multipart/form-data
• API key authentication in request headers
• source PDF upload through the files field

The file upload middleware accepts PDF uploads and one optional watermarkImage image file. For non-merge PDF actions, the first uploaded PDF file is used as the primary input.

Parameters #

action #

Type: string
Required: Yes
Accepted value: watermark

Specifies that the request should apply a watermark to the PDF document.

files #

Type: file upload (multipart/form-data)
Required: Yes

The source PDF document.

• uploaded through the files field
• must be a valid PDF upload
• for this action, the first uploaded PDF file is used as the source input

watermarkText #

Type: string
Required: Conditional

Text content used as the watermark overlay.

This field is required unless watermarkImage is uploaded.

watermarkImage #

Type: file
Required: Conditional

Image file used as the watermark overlay.

This field is required unless watermarkText is present. The public PDF route accepts one optional watermarkImage upload.

pages #

Type: string
Required: No
Default: all

Specifies which pages should receive the watermark.

Supported forms:

• all
• first
• single page such as 1
• multiple pages such as 1,3,5
• ranges such as 2-6

Values are parsed and clamped to the document page count.

opacity #

Type: number
Required: No
Default: 0.3

Controls watermark transparency.

Range: 0..1

margin #

Type: integer
Required: No
Default: 24

Defines spacing between the watermark placement and page edges when applicable.

Range clamp: 0..5000

position #

Type: string
Required: No
Default: center

Specifies watermark placement.

Supported values include:

• center
• top
• bottom
• left
• right
• corner positions

Invalid values fall back to center.

fontSize #

Type: integer
Required: No
Default: 24

Defines text size for text watermarks.

Range clamp: 1..400

color #

Type: string
Required: No
Default: #000000

Specifies text watermark color.

Accepted forms:

• #rrggbb
• #rgb

Parse fallback is black.

x #

Type: number-like
Required: No

Optional explicit horizontal placement value for watermark positioning. The public PDF parameter table lists x as a supported watermark field.

y #

Type: number-like
Required: No

Optional explicit vertical placement value for watermark positioning. The public PDF parameter table lists y as a supported watermark field.

Supported Parameters #

The Add Watermark to PDF action supports the following public parameters:

Parameter	Description
action	Must be watermark
files	Source PDF upload
watermarkText	Text watermark content
watermarkImage	Image watermark file
pages	Target pages
opacity	Watermark transparency
margin	Position margin
position	Watermark placement
fontSize	Text watermark size
color	Text watermark color
x	Optional horizontal position control
y	Optional vertical position control

These are the public watermark fields documented for /v1/pdf action=watermark.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-watermark-001" \
  -F "action=watermark" \
  -F "files=@/path/to/document.pdf" \
  -F "watermarkText=CONFIDENTIAL" \
  -F "pages=all" \
  -F "opacity=0.3" \
  -F "position=center" \
  -F "margin=24" \
  -F "fontSize=24" \
  -F "color=#000000" \
  -F "x=0" \
  -F "y=0"

This example uses the documented public field names for the PDF watermark action and includes the full supported watermark parameter surface from the public reference. watermarkText and watermarkImage are conditional alternatives, so this example uses the text-watermark path.

Success Response #

Successful /v1/pdf requests return either a single output object or a results array, depending on the action. For public documentation, watermark is safest documented as a single generated PDF output returned through a signed URL. PDF output URLs are served under /pdf/<file>.

{
  "url": "https://pixlab.davix.dev/pdf/watermarked-file.pdf",
  "request_id": "req_abc123"
}

Response Fields #

url #

Signed output URL for the generated watermarked PDF. PDF outputs are served under the public /pdf/<file> path.

request_id #

Request identifier returned by the API when available.

Errors #

The public /v1/pdf endpoint documents the following PDF-route errors:

• missing_field
• invalid_parameter
• unsupported_media_type
• pdf_page_limit_exceeded
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout
• pdf_tool_failed

The shared upload/error layer can also return:

• invalid_upload
• file_too_large
• too_many_files
• total_upload_exceeded

HTTP Status Codes #

• 400 → invalid request fields or parameters
• 413 → upload size/count limits exceeded or PDF page limit exceeded
• 415 → unsupported media type
• 429 → rate limit or monthly quota exceeded
• 503 → timeout, rate-limit store unavailable, or server busy
• 500 → PDF processing failure

Usage Notes #

Idempotency-Key is optional and supported for retry-safe request handling.

This action supports either a text watermark or an uploaded image watermark.

watermarkText is required unless watermarkImage is uploaded. watermarkImage is required unless watermarkText is present.

pages can be used to target all pages, the first page, or selected page ranges.

Output files are returned through signed URLs. Applications that need long-term storage should store generated files externally rather than treating output URLs as permanent hosting.