Documents/The PDF Toolbox

Watermarks

A watermark states ownership or status on a document before it leaves your hands: DRAFT, CONFIDENTIAL, a recipient's name, a studio's logo. The server draws it on PDFs and on images from ONE watermark object, so a contract and its scanned annexes carry the same mark. No model is involved: the work is deterministic, fast, and safe to run unattended.

1The endpoints#

Endpoint	What it does
`POST /lmkit/v1/pdf-watermark`	Lays the mark over every page, or the zero-based `pages` named, and returns the document as a file id
`POST /lmkit/v1/pdf-remove-watermark`	Takes the mark off again, leaving the rest of every page as it was
`POST /lmkit/v1/image-watermark`	Burns the mark into an image, keeping its size, format and metadata
`POST /lmkit/v1/image-convert`	The same `watermark` inside a conversion: resize, colour space and rights in one pass

Each route publishes what the engine accepts at .../capabilities (the layouts, the longest text, whether fonts are installed). Inputs follow the shared input contract, and long work rides the jobs contract.

2The watermark object#

{
  "text": "CONFIDENTIAL",
  "layout": "tile",
  "opacity": 0.3,
  "color": "#1E3A8A"
}

text, logo, or both. The logo is base64 or a stored file id (logo_file_id); its transparency is kept, so a PNG sits on the page without a box. With both, the logo leads the line.
layout: tile (default) repeats the mark on a staggered diagonal lattice, the layout that survives cropping; center draws one large mark along the diagonal; top_left, top_right, bottom_left and bottom_right draw one small mark inside the margin, the credit-line position.
Proportions, not pixels. size is a fraction of the shorter side, so a thumbnail and its master, or an A4 page and a US Letter page, carry the same-looking mark. angle, spacing and margin tune the rest.
Legible on anything. A contrasting halo (on by default) keeps the mark readable over light and dark content, and color left out picks light or dark from what the mark covers.
Every script. Text is drawn with the request's font when given, else with the fonts installed on the server, chosen per character: Arabic joins, right-to-left runs read in order, CJK and Devanagari draw. A character no font covers is refused with 422 unsupported_characters, naming it, never drawn as an empty box.

3On a PDF: vector artwork above the content#

The mark is drawn once, from the glyph outlines of its text and its logo, as a form the document references on every page. A tiled mark on a hundred pages adds a few kilobytes, stays sharp at any zoom, and prints at full resolution. It sits above the content, which is not touched: the page's text stays selectable and searchable, and the mark adds no text of its own, so search and extraction read the document exactly as before. The mark reads upright on turned pages and centres inside cropped ones.

Every copy is tagged as a watermark artifact (ISO 32000-1, 14.8.2.2). That is what lets the server find it again: marking a document twice replaces the mark (replace_existing, default true), and pdf-remove-watermark restores the pages as they rendered before.

Two documents are refused, both with 422:

Signed documents (signed_document): marking rewrites the file, which invalidates every signature. Set allow_signature_invalidation to consent, or better, mark first and sign last.
PDF/A-1 (pdfa_forbids_transparency): that part forbids the transparency a watermark needs. Convert to PDF/A-2 first; PDF/A-2 and PDF/A-3 allow it.

4On an image: burned into the pixels#

image-watermark marks any image the server decodes at its own size and writes it back in its own format when the server encodes it (else PNG), with its EXIF, XMP, IPTC and colour profile carried across (keep_metadata). page_index: -1 marks every page of a multi-page TIFF. To resize or convert in the same pass, send the same watermark to image-convert: the mark is then drawn after the resize, crisp at the size delivered.

A burned-in mark is part of the picture: unlike a PDF mark, it cannot be removed. Pair it with image-convert's rights statement so the copyright also travels machine-readable inside the file.

5Stated plainly#

A visible watermark deters reuse and states status; it does not trace a leak.
One watermark object, three surfaces, the same look everywhere.
PDF marks are vector, tagged and removable; image marks are pixels and permanent.