URL Renderer

Capture any webpage as PDF or screenshot.

Endpoint

POST /api/v1/renderer/url

Description

The URL Renderer captures any publicly accessible webpage and converts it to PDF or image format. It supports JavaScript rendering, custom viewports, authentication, and wait conditions for dynamic content.

Request Body

{
  "url": "https://example.com",
  "options": {
    "pageSize": "A4",
    "orientation": "portrait"
  }
}

Query Parameters

POST /api/v1/renderer/url?format=pdf&pageSize=A4&fullPage=true&waitUntil=load

Parameter	Type	Default	Description
format	string	pdf	Output format: pdf, png, jpg
response	string	binary	Response type: binary, base64
pageSize	string	A4	Page size: A4, A3, A5, Letter, Legal, Tabloid
orientation	string	portrait	Page orientation: portrait, landscape
viewportWidth	number	1280	Browser viewport width in pixels
viewportHeight	number	720	Browser viewport height in pixels
waitUntil	string	load	Wait condition: load, domcontentloaded, networkidle
delay	number	0	Extra delay after load in ms (0-30000)
fullPage	boolean	true	Capture full page height
quality	number	90	Image quality for JPEG (1-100)
timeout	number	30000	Render timeout in ms (1000-120000)

Options Object

{
  "url": "https://example.com",
  "options": {
    "pageSize": "A4",
    "orientation": "portrait",
    "margins": {
      "top": "20mm",
      "right": "20mm",
      "bottom": "20mm",
      "left": "20mm"
    },
    "scale": 1,
    "printBackground": true,
    "viewportWidth": 1280,
    "viewportHeight": 720,
    "waitUntil": "load",
    "waitForSelector": ".content-loaded",
    "waitForSelectorTimeout": 10000,
    "delay": 2000,
    "timeout": 30000,
    "fullPage": true,
    "quality": 90,
    "omitBackground": false,
    "clip": {
      "x": 0,
      "y": 0,
      "width": 800,
      "height": 600
    },
    "headers": {
      "Accept-Language": "en-US"
    },
    "httpAuth": {
      "username": "user",
      "password": "pass"
    }
  }
}

Query Parameters Take Precedence

When the same option is specified in both query params and body options, the query parameter value is used.

Options Reference

format

Output format for the rendered document.

Value	Description
pdf	PDF document (default)
png	PNG image
jpg	JPEG image

pageSize

Page size for PDF output.

Value	Dimensions
A4	210mm × 297mm (default)
A3	297mm × 420mm
A5	148mm × 210mm
Letter	8.5" × 11"
Legal	8.5" × 14"
Tabloid	11" × 17"

orientation

Page orientation for PDF output.

Value	Description
portrait	Vertical orientation (default)
landscape	Horizontal orientation

margins

Page margins for PDF output. Same format as HTML renderer.

scale

Scale factor for the content.

• Range: 0.1 to 2
• Default: 1

printBackground

When true, includes CSS backgrounds and background images in the output.

viewportWidth / viewportHeight

Browser viewport dimensions in pixels. Affects how the page is rendered.

• viewportWidth default: 1280
• viewportHeight default: 720

waitUntil

Condition to wait for before capturing.

Value	Description
load	Wait for load event (default, most reliable)
domcontentloaded	Wait for DOMContentLoaded event
networkidle	Wait until network is idle (fewer than 2 connections for 500ms)

tip

Default waitUntil: 'load' is more reliable than networkidle for sites with Cloudflare protection. The renderer has automatic fallback - if navigation times out, it retries with domcontentloaded.

waitForSelector

CSS selector to wait for before capturing. Useful for dynamic content.

{
  "waitForSelector": ".main-content",
  "waitForSelectorTimeout": 10000
}

note

waitForSelector is non-blocking - if the selector is not found within the timeout, rendering continues anyway.

waitForSelectorTimeout

Maximum time to wait for waitForSelector in milliseconds.

• Default: 10000

delay

Extra delay in milliseconds after the wait condition is satisfied. Useful for pages with animations.

• Range: 0 to 30000
• Default: 0

timeout

Maximum time to wait for rendering in milliseconds.

• Range: 1000 to 120000
• Default: 30000

fullPage

When true, captures the entire page content including content below the fold.

quality

JPEG compression quality.

• Range: 1 to 100
• Default: 90

omitBackground

When true, renders with a transparent background (PNG only).

clip

Capture a specific area of the page instead of the full viewport.

{
  "clip": {
    "x": 100,
    "y": 100,
    "width": 500,
    "height": 400
  }
}

headers (body only)

Custom HTTP headers to send with the request.

{
  "headers": {
    "Accept-Language": "de-DE",
    "Cookie": "session=abc123"
  }
}

httpAuth (body only)

HTTP Basic Authentication credentials.

{
  "httpAuth": {
    "username": "admin",
    "password": "secret"
  }
}

Examples

Basic PDF Capture

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }' \
  --output webpage.pdf

Full Page Screenshot

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url?format=png&fullPage=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }' \
  --output screenshot.png

Custom Viewport (Mobile)

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url?format=png&viewportWidth=375&viewportHeight=812" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }' \
  --output mobile-screenshot.png

Wait for Dynamic Content

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://spa-app.example.com",
    "options": {
      "waitUntil": "networkidle",
      "waitForSelector": ".content-loaded",
      "delay": 2000
    }
  }' \
  --output spa-capture.pdf

With Query Params

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url?format=pdf&pageSize=A4&fullPage=true&waitUntil=load" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  --output webpage.pdf

Authenticated Page

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://protected.example.com/dashboard",
    "options": {
      "httpAuth": {
        "username": "admin",
        "password": "secret"
      }
    }
  }' \
  --output dashboard.pdf

Specific Area Capture

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/url?format=png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "clip": {
        "x": 0,
        "y": 0,
        "width": 800,
        "height": 600
      }
    }
  }' \
  --output cropped.png

Response

Success (Binary)

• Status: 200 OK
• Content-Type: application/pdf, image/png, or image/jpeg
• Body: Raw binary data

Success (Base64)

{
  "data": "<base64-encoded-content>",
  "contentType": "application/pdf"
}

Error Response

{
  "error": "Bad Request",
  "message": "URL is required",
  "statusCode": 400
}

Navigation Error

{
  "error": "Navigation Error",
  "message": "Failed to load URL: net::ERR_NAME_NOT_RESOLVED",
  "statusCode": 422
}