Inkspan › Guides › Watermark PDF API

Watermark PDF API

Stamp DRAFT, CONFIDENTIAL, or any text across every page of a PDF in one call — for document control and review workflows.

Treat it as a label rather than a security control: the stamp is a normal content object and can be removed with an editor.

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

Is there a free tier?

Yes — 100 documents a month, no card required. Usage-based plans start at $19/month when you outgrow it.

How do I authenticate?

Send your key in the X-API-Key header on every request.

Do failed requests count against my quota?

No. Only successful requests are metered.

Get a free API key →

Full guides for /v1/pdf/watermark: cURL · Python · Node.js · all guides