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 20 MB, 8 pages.
/watermarks/documents- Upload
- 20 MB · 8 pages
- Output
- Selectable PDF
- CPU cost
- 1 credit / page
Request
Send a PDF and a JSON reference object that is not empty. Your API key needs the
watermarks:embed permission.
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 PDF. A 202 response returns a job receipt
instead, so check the status before you save the body as a PDF. 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 |
| Background embed / detect | Append /async to either endpoint |
- Embed
- Endpoint
POST/watermarks /documents
- Detect
- Endpoint
POSTwith/watermarks /documents /detect fileandwatermarks:detect
- 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.
Jobs · GPU · Storage.
Supported files
| Requirement | Limit |
|---|---|
| Document | Passive, unencrypted PDF; 1–8 unrotated pages with standard page units |
| Upload / output / detection | 20 MB / 64 MB / 64 MB |
| Rendered pixels at 144 dpi | 4 MP per page; 16.8 MP total, enough for eight A4 or US Letter pages |
| Page content | Text, vectors, scanned images or a mixture |
| Unsupported | Forms, digital signatures, active content and annotation types not listed below |
- Document
- Limit
- Passive, unencrypted PDF; 1–8 unrotated pages with standard page units
- Upload / output / detection
- Limit
- 20 MB / 64 MB / 64 MB
- Rendered pixels at 144 dpi
- Limit
- 4 MP per page; 16.8 MP total, enough for eight A4 or US Letter pages
- Page content
- Limit
- Text, vectors, scanned images or a mixture
- Unsupported
- Limit
- Forms, digital signatures, active content and annotation types not listed below
Text stays searchable and selectable. Fonts, vectors, page sizes, supported annotations and document metadata stay the same. The watermark is stored in added textures, which can make the file larger. Editing the layout or removing those textures can affect recovery.
Annotations, attachments and active content
- Retained: links, text notes, popups and static
PlyBorderannotations, including relationships and appearance streams. Borders need a normal Form appearance; actions on notes, popups and borders are unsupported. - JSON attachments: retained byte-for-byte, not watermarked. Require a
.jsonname,applicationtype and valid UTF-8 JSON object/array. Maximum 64 nesting levels, 64 KB each, 256 KB total and 16 files./json - Removed: document/page open actions, additional actions and document-level JavaScript that run automatically.
- Rejected: other active content (including scripts on links), non-JSON attachments, forms and digital signatures. Scanned handwritten signatures are ordinary page content.
Annotations are retained separately and do not receive their own watermark.
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.
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.
Billing and results
- Embed: one CPU credit per page, so an eight-page PDF costs 8. If the request fails, the reserved credits are refunded.
- Detect: one CPU credit per PDF, whatever its page count.
unitsreports each page. The top-level watermark ID is present only when Etchv finds the same watermark on every page. - 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 PDF bytes. Save the file using the
returned filename and the application content type. The other SDKs
also support PDFs. DOCX and PPTX are not yet supported.
Asset library
X-Asset-ID identifies the saved output. X-Source-Asset-ID identifies the original.
Manage files and retention.