API reference

PDF watermarking

PDF watermarking API reference: watermark PDF pages while keeping text selectable and vector content intact. Pages are not flattened. Up to 50 MB and 2,000 pages.

POST/watermarks/documents
Upload
PDF 50 MB · DOCX, PPTX 20 MB
Output
Same format, editable
CPU cost
1 credit / page or unit

Request

Send a PDF, DOCX or PPTX and a JSON reference object that is not empty. Your API key needs the watermarks:embed permission. The result is the same format: a PDF stays a PDF, and Word and PowerPoint files stay editable.

Shell
curl --fail-with-body https://api.etchv.com/watermarks/documents \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -H "Idempotency-Key: investor-preview-42" \
  -F 'file=@presentation.pdf' \
  --form-string 'data={"delivery":"investor-preview-42"}' \
  -D response-headers.txt --output response-body

A 200 response returns the watermarked file. A 202 response returns a job receipt instead, so check the status before you save the body as a document. Save the watermark ID from the X-Watermark-ID header with your record. Response headers and request options.

Choose sync or async

OperationEndpoint
EmbedPOST /watermarks/documents
DetectPOST /watermarks/documents/detect with file and watermarks:detect; a PDF over 32 pages may return 202 with a job receipt
Background embed / detectAppend /async to either endpoint
Embed
Endpoint
POST /watermarks/documents
Detect
Endpoint
POST /watermarks/documents/detect with file and watermarks:detect; a PDF over 32 pages may return 202 with a job receipt
Background embed / detect
Endpoint
Append /async to either endpoint

Async requests support webhook_id. Both modes support accelerator=gpu on Business and Enterprise plans. Embedding also supports storage_destination_id and storage_key, and for a PDF, active_content (scripts and actions). Jobs · GPU · Storage.

Supported files

RequirementLimit
DocumentAny PDF that opens without a password: 1 to 2,000 pages, any page size or rotation
Upload / output / detection50 MB / 95 MB / 95 MB. The watermark adds up to about 48 KB per page, so a long PDF must leave that room under 95 MB: a 2,000-page PDF can be up to about 1 MB
Page contentText, vectors, scanned images, forms, annotations or a mixture
Not supportedPDFs that need a password to open: remove the open password first
Document
Limit
Any PDF that opens without a password: 1 to 2,000 pages, any page size or rotation
Upload / output / detection
Limit
50 MB / 95 MB / 95 MB. The watermark adds up to about 48 KB per page, so a long PDF must leave that room under 95 MB: a 2,000-page PDF can be up to about 1 MB
Page content
Limit
Text, vectors, scanned images, forms, annotations or a mixture
Not supported
Limit
PDFs that need a password to open: remove the open password first

Text stays searchable and selectable. Everything else stays as it was: fonts, vectors, page sizes, links, bookmarks, form fields and their values, annotations, attachments, scripts and metadata. Only page thumbnails, small pictures of the original pages, are removed; viewers draw their own. The watermark is two small textures drawn over each page, which add about 25 KB per page (rarely up to 48 KB). Editing the layout or removing those textures can affect recovery.

Forms, signatures, encryption and large pages
  • Forms: fields and their values are unchanged and stay fillable. The watermark is in the page content underneath them.
  • Digital signatures: the watermark is added as an incremental update after the signed revision, so existing signatures stay valid for what was signed. PDF viewers show that the document changed after signing. The signed revision underneath keeps everything it had, page thumbnails included. A signed PDF that is also encrypted, or that has to be repaired before it opens, is written again instead, and its signatures no longer verify.
  • Encryption: a PDF with only an owner (permissions) password is watermarked and keeps its encryption and permissions; your owner password still works.
  • Annotations: notes, stamps, highlights and other annotations are retained and do not receive their own watermark.
  • Very large pages: a page above 4 megapixels at 144 dpi, such as a map or a poster, is watermarked and detected at a proportionally lower resolution.
  • Very narrow pages: a page under 128 points (about 1.8 inches) on its shorter side, such as a strip or a label, is watermarked and detected at a higher resolution, so its shorter side renders at least 256 pixels across.
Scripts and actions

By default (active_content=keep), scripts, actions, form fields and attachments come back exactly as you uploaded them. Etchv never runs them.

With active_content=remove_auto_run, Etchv also removes what a PDF viewer runs by itself, without the reader acting:

  • the action run when the document opens (a page to open at is not an action and stays);
  • additional actions of the document and its pages, and document-level JavaScript;
  • annotation actions that run when a page opens, closes or comes into view;
  • XFA forms, whose scripts Acrobat runs on open (the regular form fields stay; a form built only in XFA, with no regular fields, shows its placeholder page instead);
  • rich media and 3D content set to start on its own, which then starts on a click.

Links, form fields with their keystroke, format, calculation and click scripts, and attachments stay, because they run only when the reader acts. Form calculations that rely on document-level JavaScript may stop working. In a digitally signed PDF the watermark is a later revision, so the signed revision underneath keeps what it had: a viewer that shows the signed version shows it as it was signed.

Shell
curl --fail-with-body "https://api.etchv.com/watermarks/documents?active_content=remove_auto_run" \
  -H "X-API-Key: $ETCHV_API_KEY" \
  -F 'file=@contract.pdf' \
  --form-string 'data={"recipient":"counsel-7"}' --output contract-watermarked.pdf

The option is part of the request: an Idempotency-Key reused with a different value returns 409. remove_auto_run applies to PDFs only and returns 422 for a DOCX or PPTX; the image and video endpoints refuse the option. Batches take it for every file, and remove_auto_run needs every file to be a PDF.

Rendering and verification

Etchv must detect the exact watermark on each final page. Each page must also meet 35 dB PSNR, a measure of how close the result looks to the original. Etchv checks this with two PDF rendering engines, using a standard 144 dpi RGB rendering with annotations hidden. Two blended textures carry the watermark; pages are not flattened.

On the rare page that the two engines draw differently (a damaged page one of them cannot draw, for example), the watermark is checked in the engine detection uses, and the other engine still has to meet the quality limit.

Embed fonts in your source PDFs so they render the same everywhere. Etchv does not add fonts to your PDF. Its verification render uses standard substitute fonts, and other viewers may choose different ones. Printing, re-saving and edits can affect recovery.

DOCX and PPTX

RequirementLimit
FilesDOCX and PPTX (Office Open XML); not macro-enabled, templates, slide shows or password-protected
Upload / output / detection20 MB / 100 MB / 95 MB in one request, 100 MB through a large-file upload
Watermark unitsUp to 128 page or slide watermarks and images, 40 MP in total
Slide backgroundsSolid colors, pictures and linear gradients; pattern fills, tiled pictures and path gradients are not supported yet, and a stereo, multi-angle or panorama JPEG background is refused
Files
Limit
DOCX and PPTX (Office Open XML); not macro-enabled, templates, slide shows or password-protected
Upload / output / detection
Limit
20 MB / 100 MB / 95 MB in one request, 100 MB through a large-file upload
Watermark units
Limit
Up to 128 page or slide watermarks and images, 40 MP in total
Slide backgrounds
Limit
Solid colors, pictures and linear gradients; pattern fills, tiled pictures and path gradients are not supported yet, and a stereo, multi-angle or panorama JPEG background is refused

The watermark is carried in units:

  • Pages. Every Word header that a page shows gets a page-sized picture behind the text, made from the page's own color with the watermark. Sections without a header get one that holds only this picture.
  • Slides. Every slide, including hidden slides, gets its background as a picture with the watermark. Slides with the same background share one. A gradient background becomes a picture of the gradient.
  • Images. Every JPEG, PNG, GIF, BMP or TIFF image of at least 64 pixels on each side is watermarked in its own format. Smaller images, animations, GIFs over 1 MP, stereo, multi-angle and panorama JPEGs, and vector graphics are unchanged, and the rest of the document is still watermarked. A JPEG that holds more images after the photo, such as an HDR gain map, becomes a JPEG of the photo alone, as for image uploads. A mostly transparent image that cannot carry the watermark within the quality limit, such as a few lines of text on a clear background, is also left unchanged, as long as the page or slide pictures and every other image carry it.

Text, tables, fields, tracked changes, comments, notes, animations and layouts are unchanged. The file's preview thumbnail, a picture of the original's first page or slide, is removed; Word and PowerPoint save a new one. Etchv must detect the exact watermark in every unit it watermarks in the final file, and each unit must meet 35 dB PSNR.

Billing and results

  • Embed: one CPU credit per PDF page, so an eight-page PDF costs 8. A DOCX or PPTX costs one credit per watermark unit: each page or slide background picture and each image. If the request fails, the reserved credits are refunded.
  • Detect: one CPU credit per file, whatever its page count. A PDF over 32 pages is detected as a job: the response is its result when it finishes in time, otherwise a 202 receipt. A detection answered in the request can be sent again with its Idempotency-Key at no extra charge. units reports each PDF page, or each DOCX/PPTX unit with its part name. For a PDF, the top-level watermark ID is present only when Etchv finds the same watermark on every page; for a DOCX or PPTX, on every unit that carries one, so images added later do not hide it.
  • Retrieve: job results last 24 hours. A retry with the same idempotency key returns the saved file without another charge.

SDKs

SDKEmbed / detect
Pythonembed_document / detect_document
Node.jsembedDocument / detectDocument
Python
Embed / detect
embed_document / detect_document
Node.js
Embed / detect
embedDocument / detectDocument

In these SDKs, the image field contains the document bytes. Save the file using the returned filename and content type. The other SDKs also support PDFs.

Asset library

X-Asset-ID identifies the saved output. X-Source-Asset-ID identifies the original. Manage files and retention.

View source on GitHub

Your privacy, your choice

We use essential cookies to keep Etchv working. Optional analytics helps us improve the site. Analytics is on by default; you can turn it off in preferences. PostHog loads only if you accept all. Privacy policy

ETCHV

Privacy preferences

Choose what you allow on this browser. Analytics is enabled by default. You can turn it off, and change your choice at any time.

Essential

Always active

Supports secure sign-in, account sessions, site security, and remembering your privacy choice. These are needed for Etchv to work.

Analytics

Helps us understand visits and improve the website using page-view and device statistics, which do not use cookies. PostHog also measures visits and campaigns and may set cookies; it loads only after you save a choice with analytics on. Turning this off stops future analytics events.

We do not load advertising scripts. Meeting calendars load only when you open them. These preferences do not change your account, watermarking requests, or asset storage.

Your choice is remembered for 180 days on this browser. Privacy policy