POST/api/v1/pdf/watermark

Add Watermark

Add customizable text watermarks to PDF documents. Supports dynamic variables like dates, page numbers, and filenames. Control position, opacity, font size, color, and target specific pages.

Content-Type: multipart/form-data

Parameters

Parameter	Type	Required	Default	Description
`file`	file	Required	-	The PDF file to watermark.
`text`	string	Required	-	Watermark text. Supports dynamic variables (see below).
`position`	string	Optional	`diagonal`	One of: `diagonal`, `center`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`.
`opacity`	float	Optional	`0.3`	Watermark opacity. Range: 0.05 to 1.0.
`font_size`	integer	Optional	`48`	Font size in points. Range: 8 to 200.
`font_color`	string	Optional	`#808080`	Hex color code for the watermark text.
`pages`	string	Optional	`all`	Which pages to watermark. One of: `all`, `first`, `last`, `odd`, `even`, or custom ranges (e.g. `1-3,5`).

Dynamic Variables

Use these placeholders in the text parameter. They are replaced at render time for each page.

Variable	Description	Example Output
`{{date}}`	Current date	2026-03-07
`{{datetime}}`	Current date and time	2026-03-07 14:30:00
`{{page}}`	Current page number	3
`{{total_pages}}`	Total page count	12
`{{filename}}`	Original filename	report.pdf

Code Examples

cURL

bash

curl -X POST "https://app.alternapdf.com/api/v1/pdf/watermark" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "text=CONFIDENTIAL - {{date}}" \
  -F "position=diagonal" \
  -F "opacity=0.3" \
  -F "font_size=48" \
  -F "font_color=#808080" \
  -F "pages=all" \
  --output watermarked.pdf

Python

python

import requests

url = "https://app.alternapdf.com/api/v1/pdf/watermark"
headers = {"X-API-Key": "YOUR_API_KEY"}

files = {
    "file": ("document.pdf", open("document.pdf", "rb"), "application/pdf"),
}

data = {
    "text": "CONFIDENTIAL - {{date}}",
    "position": "diagonal",
    "opacity": "0.3",
    "font_size": "48",
    "font_color": "#808080",
    "pages": "all",
}

response = requests.post(url, headers=headers, files=files, data=data)

with open("watermarked.pdf", "wb") as f:
    f.write(response.content)

print(f"Watermarked PDF saved ({len(response.content)} bytes)")

JavaScript

javascript

const fs = require("fs");
const FormData = require("form-data");
const axios = require("axios");

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("text", "CONFIDENTIAL - {{date}}");
form.append("position", "diagonal");
form.append("opacity", "0.3");
form.append("font_size", "48");
form.append("font_color", "#808080");
form.append("pages", "all");

const response = await axios.post(
  "https://app.alternapdf.com/api/v1/pdf/watermark",
  form,
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      ...form.getHeaders(),
    },
    responseType: "arraybuffer",
  }
);

fs.writeFileSync("watermarked.pdf", response.data);
console.log(`Watermarked PDF saved (${response.data.byteLength} bytes)`);

Response

200Watermarked PDF binary

Header	Value
`Content-Type`	application/pdf
`Content-Disposition`	attachment; filename="watermarked.pdf"

The response body contains the watermarked PDF binary. Save it directly to a file. On error, a JSON object with a detail field is returned instead.