Inkspan › Guides › How to add a watermark to a PDF in Python

How to add a watermark to a PDF in Python

The /v1/pdf/watermark endpoint stamps a line of text across every page of a document in light grey, over the existing content. It is built for document-control workflows — marking drafts, flagging confidential copies, and labelling documents sent for review so they are not mistaken for final versions.

The watermark is applied to every page in one request, and the output is a normal PDF you can pass straight to another endpoint such as merge or compress.

Also in: cURL · Node.js

Python example

import requests

files = {'file': open('input.pdf', 'rb')}
data = {'text': "CONFIDENTIAL"}

r = requests.post(
    'https://api.inkspan.dev/v1/pdf/watermark',
    headers={'X-API-Key': 'ink_live_...'},
    files=files, data=data,
)
r.raise_for_status()
with open('watermarked.pdf', 'wb') as f:
    f.write(r.content)

Request parameters

Name	Type	Required	Description
`file`	file	yes	The PDF to watermark.
`text`	string	no	Watermark text. Defaults to `CONFIDENTIAL`.

Response

Returns a PDF as a binary stream with Content-Type: application/pdf and Content-Disposition: attachment; filename=watermarked.pdf. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

The watermark is drawn as text at a fixed size and position, not scaled to fit. Very long strings can overflow the page — keep it to roughly one or two words.
It is an overlay, so it sits on top of content rather than behind it. Light grey keeps the underlying text readable.
This marks a document; it does not protect it. The text is a normal content object and can be removed by anyone with an editor.
Watermarking rasterised scans works the same way, since the stamp is drawn over whatever is already on the page.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

Can I control colour, angle, or opacity?

Not through this endpoint — it applies one house style. For full control, render your own overlay with /v1/generate/html and composite it.

Is the watermark on every page?

Yes, every page of the document receives the same stamp in a single call.

Can it be removed?

Yes, by anyone with a PDF editor. Treat it as a label, not a security control.

Get a free API key →

Related Manipulate guides: merge PDF files · split a PDF into pages · compress a PDF · convert a PDF to images · fill a PDF form