PDF Options

Docs

PDF Options

Configure PDF document generation settings including orientation, scale, and margins.

Options for PDF format. These settings are passed in options.pdfOptions. PDF dimensions are derived from the viewport width and height.

Options

Field	Type	Default	Notes
`landscape`	`boolean`	`false`	Generate PDF in landscape orientation.
`scale`	`number (0.1-2)`	`1`	Scale factor for rendering.
`margins`	`PdfMargins`	—	Page margins. See below.

Margins

Each margin property accepts CSS-style values:

Field	Type	Notes
`top`	`string`	Top margin (e.g., `"1cm"`, `"0.5in"`, `"20px"`).
`right`	`string`	Right margin.
`bottom`	`string`	Bottom margin.
`left`	`string`	Left margin.

Supported Units

Unit	Example	Notes
`cm`	`"1cm"`	Centimeters
`mm`	`"10mm"`	Millimeters
`in`	`"0.5in"`	Inches
`px`	`"20px"`	Pixels (at 96 DPI)

Scale Factor

The scale parameter adjusts the rendering size:

Scale	Use Case
`0.5-0.9`	Fit more content on each page, smaller text
`1.0`	Default, 1:1 rendering
`1.1-2.0`	Larger text and elements, fewer pages

Scale values outside the 0.1-2 range will be rejected with a validation error.

Viewport and Page Size

PDF page dimensions are calculated from the viewport you specify:

Portrait: Page width = viewport width, page height = viewport height
Landscape: Page width = viewport height, page height = viewport width

Common viewport configurations for standard paper sizes:

Paper Size	Viewport (Portrait)	Viewport (Landscape)
A4	`794 × 1123`	`1123 × 794`
Letter	`816 × 1056`	`1056 × 816`
Legal	`816 × 1344`	`1344 × 816`

Example Request

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://site.com/"
    ],
    "viewports": [
      {
        "width": 1280,
        "height": 800
      }
    ],
    "options": {
      "format": "pdf",
      "pdfOptions": {
        "landscape": false,
        "scale": 1,
        "margins": {
          "top": "1cm",
          "right": "1cm",
          "bottom": "1cm",
          "left": "1cm"
        }
      }
    }
  }' \
  "https://api.watchero.io/api/v1/snapshots"

Use Cases

Reports and Documentation

Generate archival PDFs of web content for compliance or record-keeping:

{
  "options": {
    "format": "pdf",
    "pdfOptions": {
      "margins": {
        "top": "2cm",
        "right": "2cm",
        "bottom": "2cm",
        "left": "2cm"
      }
    }
  }
}

Print-Ready Output

For content designed for physical printing:

{
  "viewports": [{ "width": 794, "height": 1123 }],
  "options": {
    "format": "pdf",
    "pdfOptions": {
      "scale": 1,
      "margins": {
        "top": "0.5in",
        "right": "0.5in",
        "bottom": "0.5in",
        "left": "0.5in"
      }
    }
  }
}

Image Options Block Options