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.
/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.
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-bodyA 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
| Operation | Endpoint |
|---|---|
| Embed | POST |
| Detect | POST with file and watermarks:detect; a PDF over 32 pages may return 202 with a job receipt |
| Background embed / detect | Append /async to either endpoint |
- Embed
- Endpoint
POST/watermarks /documents
- Detect
- Endpoint
POSTwith/watermarks /documents /detect fileandwatermarks:detect; a PDF over 32 pages may return202with a job receipt
- Background embed / detect
- Endpoint
- Append
/asyncto 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
| Requirement | Limit |
|---|---|
| Document | Any PDF that opens without a password: 1 to 2,000 pages, any page size or rotation |
| Upload / output / detection | 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 | Text, vectors, scanned images, forms, annotations or a mixture |
| Not supported | PDFs 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.
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.pdfThe 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
| Requirement | Limit |
|---|---|
| Files | DOCX and PPTX (Office Open XML); not macro-enabled, templates, slide shows or password-protected |
| Upload / output / detection | 20 MB / 100 MB / 95 MB in one request, 100 MB through a large-file upload |
| Watermark units | Up to 128 page or slide watermarks and images, 40 MP in total |
| Slide backgrounds | 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 |
- 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
202receipt. A detection answered in the request can be sent again with itsIdempotency-Keyat no extra charge.unitsreports each PDF page, or each DOCX/PPTX unit with itspartname. 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
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.