> ## Documentation Index
> Fetch the complete documentation index at: https://pdfbase.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add watermark

> Add a text or image watermark to an existing PDF.

## Phase

**Phase 2**

## Request

<ParamField body="source" type="object" required>
  The PDF to watermark. One of:

  * `{ "pdf_id": "pdf_abc123" }`
  * `{ "url": "https://example.com/doc.pdf" }`
  * `{ "base64": "JVBERi0x..." }`
</ParamField>

<ParamField body="text" type="object">
  Text watermark config. Mutually exclusive with `image`.

  * `content` (string, required) — The watermark text, e.g., "CONFIDENTIAL", "DRAFT".
  * `font_size` (integer, default: 48) — Font size in points.
  * `color` (string, default: "#00000020") — Color with alpha, hex format.
  * `rotation` (number, default: -45) — Rotation in degrees.
  * `position` (string, default: "center") — One of: `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`.
</ParamField>

<ParamField body="image" type="object">
  Image watermark config. Mutually exclusive with `text`.

  * `url` (string) — URL to the watermark image (PNG, JPEG, SVG).
  * `base64` (string) — Base64-encoded image. Use this or `url`, not both.
  * `width` (string, default: "200px") — Image width.
  * `opacity` (number, default: 0.1) — Range: 0.0 to 1.0.
  * `position` (string, default: "center") — Same options as text watermark.
</ParamField>

<ParamField body="pages" type="string" default="all">
  Which pages to watermark. `"all"`, `"1-3"`, `"1,3,5"`, or `"odd"`/`"even"`.
</ParamField>

<ParamField body="layer" type="string" default="over">
  `over` — watermark renders on top of content. `under` — watermark renders behind content.
</ParamField>

<ParamField body="output" type="string" default="url">
  `url` or `base64`.
</ParamField>

## Response

```json theme={null}
{
  "id": "pdf_watermarked1",
  "object": "pdf",
  "status": "completed",
  "url": "https://files.pdfbase.dev/pdf_watermarked1.pdf?token=sig_abc",
  "pages": 10,
  "bytes": 1280000,
  "watermark": {
    "type": "text",
    "content": "CONFIDENTIAL",
    "pages_applied": 10
  },
  "created_at": "2026-05-19T12:15:00Z",
  "expires_at": "2026-05-20T12:15:00Z"
}
```

## Example

```bash theme={null}
curl -X POST https://api.pdfbase.dev/v1/pdfs/watermark \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "pdf_id": "pdf_contract" },
    "text": {
      "content": "DRAFT",
      "font_size": 72,
      "color": "#FF000015",
      "rotation": -45,
      "position": "center"
    },
    "pages": "all",
    "layer": "over",
    "output": "url"
  }'
```