How to add a text watermark to a PDF with an API

Updated 2026-11-10

Use when a PDF must be stamped with a text mark such as DRAFT or CONFIDENTIAL on its pages. Add output=url for a 24 h link.

From an MCP client, add https://tanod.dev/mcp and call pdf_watermark; its free daily calls are applied automatically, no key or signup.

POST a PDF and the watermark text to /v1/pdf/watermark. It returns the PDF with the text stamped on every page, or on the pages you select.

Request

text is Latin (Windows-1252) text. Optional: font (one of 6 built-in fonts), font_size (default 48), opacity (0.3), angle (45, counter-clockwise), position (9 choices, default center), color, layer (over or under the content) and pages.

curl, using the free tier
curl -s -X POST https://tanod.dev/v1/pdf/watermark \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "text": "DRAFT"}'

The file comes back as base64 in the JSON. To save it, pipe the response through jq and base64:

save the result to a file
curl -s -X POST https://tanod.dev/v1/pdf/watermark \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "text": "DRAFT"}' \
  | jq -r '.file.data_base64' | base64 -d > watermarked.pdf

Response

Response (example from the API spec, trimmed)
{
  "operation": "watermark",
  "input_bytes": 13264,
  "input_pages": 1,
  "stamped_pages": 1,
  "file": {
    "name": "watermarked.pdf",
    "content_type": "application/pdf",
    "bytes": 13676,
    "pages": 1,
    "data_base64": "JVBERi0xLjQKJb/3"
  },
  "output_bytes": 13676,
  "active_content_removed": {},
  "untrusted_content": true
}

Limits and caveats

To pay by card, run the same PDF operations as an Apify actor, PDF Toolkit (tanod/pdf-toolkit), billed through your Apify account at USD 0.01 per PDF processed (merge, split, extract or remove pages, rotate, watermark, page numbers, protect or unlock; a merge of up to 20 PDFs counts once) or USD 0.015 per PDF compressed, plus Apify's small start fee per run. Failed PDFs and invalid links are free.

Text outside Windows-1252 is a 422 unsupported_text.

The watermark is added as an extra layer; the original content is never rewritten. Anyone can remove it with a PDF editor, so it deters casual reuse only.

JavaScript, launch and submit actions, embedded files and XFA forms are always stripped from the output and counted in active_content_removed. Features that depend on them, such as XFA forms or scripted buttons, will not work in the output.

Encrypted input is a 422 pdf_encrypted; unlock it first.

To watermark by hand, use the free PDF watermark tool in your browser.

Add "output": "url" to the request and the file is stored for 24 hours and returned as a link (url, expires_at, sha256) instead of base64, which keeps it out of your context window. The price is the same. How the links work.

Price and free allowance

USD 0.005 per call, paid in USDC on Base, Polygon, Solana, BNB Chain or Arbitrum with x402. 3 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared by merge, split, extract and remove pages, rotate, watermark, page numbers, protect, unlock and metadata. MCP tool: pdf_watermark at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/docs?via=pdf-watermark-api as a custom connector (steps), then ask in plain words, for example "Stamp DRAFT across every page of this PDF." The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.

Related guides: How to add page numbers to a PDF with an API, How to password-protect a PDF with an API, How to rotate the pages of a PDF with an API. Back to tanod.dev or the guide index. Results are automated and heuristic.