MegaPDF - Free PDF Converter, Editor, OCR & Unlock PDF

The Watermark API allows you to add text or image watermarks to PDF documents. You can customize the position, opacity, rotation, and other properties of the watermark for branding, copyright protection, or document classification.

Endpoint

POST https://api.mega-pdf.com/api/pdf/watermark

Authentication

Authenticate requests using an API key in the x-api-key header.

// Header example
x-api-key: your-api-key

Request Parameters

The API accepts multipart/form-data requests with the following parameters:

Parameter	Type	Description	Required
`file`	File	PDF file to watermark (max 50MB)	Yes
`watermarkType`	String	Type of watermark: `text` or `image`	Yes
`text`	String	Text for watermark (required if watermarkType is text)	Conditional
`textColor`	String	Color for text watermark (hex format, e.g., #FF0000)	No (default: #FF0000)
`fontSize`	Integer	Font size for text watermark (8-120)	No (default: 48)
`fontFamily`	String	Font family for text watermark	No (default: Helvetica)
`watermarkImage`	File	Image file for watermark (required if watermarkType is image)	Conditional
`position`	String	Watermark position: center, top-left, top-right, bottom-left, bottom-right, custom, tile	No (default: center)
`rotation`	Integer	Rotation angle (0-360 degrees)	No (default: 0)
`opacity`	Integer	Watermark opacity (1-100)	No (default: 30)
`scale`	Integer	Image scale percentage (10-100, only for image watermarks)	No (default: 50)
`pages`	String	Pages to apply watermark to (all, even, odd, or custom)	No (default: all)
`customPages`	String	Custom page range (e.g., '1-3,5,7-9', required if pages is custom)	Conditional
`customX`	Integer	Custom X position percentage (0-100, required if position is custom)	Conditional
`customY`	Integer	Custom Y position percentage (0-100, required if position is custom)	Conditional

Example Request

Add a text watermark to a PDF using cURL:

curl -X POST https://api.mega-pdf.com/api/pdf/watermark \
  -H "x-api-key: your-api-key" \
  -F "file=@/path/to/document.pdf" \
  -F "watermarkType=text" \
  -F "text=CONFIDENTIAL" \
  -F "textColor=#FF0000" \
  -F "fontSize=72" \
  -F "opacity=30" \
  -F "position=center" \
  -F "rotation=45"

Add an image watermark to a PDF using cURL:

curl -X POST https://api.mega-pdf.com/api/pdf/watermark \
  -H "x-api-key: your-api-key" \
  -F "file=@/path/to/document.pdf" \
  -F "watermarkType=image" \
  -F "watermarkImage=@/path/to/logo.png" \
  -F "opacity=50" \
  -F "position=bottom-right" \
  -F "scale=30"

Response Format

Successful responses include the watermarked file URL:

{
  "success": true,
  "message": "Watermark added to PDF successfully",
  "fileUrl": "/api/file?folder=watermarked&filename=uuid-watermarked.pdf",
  "filename": "uuid-watermarked.pdf",
  "originalName": "document.pdf",
  "fileSize": 1234567,
  "totalPages": 5,
  "billing": {
    "usedFreeOperation": true,
    "freeOperationsRemaining": 9,
    "currentBalance": 10.50,
    "operationCost": 0.00
  }
}

Error responses:

{
  "success": false,
  "error": "Text is required for text watermarks"
}

Code Examples

Using the Watermark API with JavaScript:

const formData = new FormData();
formData.append('file', fs.createReadStream('document.pdf'));
formData.append('watermarkType', 'text');
formData.append('text', 'DRAFT');
formData.append('textColor', '#0000FF'); // Blue
formData.append('fontSize', '60');
formData.append('opacity', '40');
formData.append('rotation', '30');
formData.append('position', 'center');
formData.append('pages', 'all');

fetch('https://api.mega-pdf.com/api/pdf/watermark', {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key'
  },
  body: formData
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Watermark added successfully:', data.fileUrl);
    } else {
      console.error('Failed to add watermark:', data.error);
    }
  })
  .catch(error => console.error('Error:', error));