Documentation

Screenshot API Reference

Capture pixel-perfect screenshots from any URL or HTML content. Supports full-page captures, element selection, custom viewports, and more.

Endpoints

Method Endpoint Description
POST /v2/screenshot Capture a screenshot (sync)
POST /v2/screenshot/async Capture a screenshot (async with webhook)

Request Parameters

Source (Required - one of)

Parameter Type Description
url string URL to capture. Must be publicly accessible.
html string Raw HTML content to render and capture.

Viewport Options

Parameter Type Default Description
viewport.width number 1920 Viewport width in pixels (100-3840)
viewport.height number 1080 Viewport height in pixels (100-3840)
viewport.deviceScaleFactor number 1 Device pixel ratio (1-3)
viewport.isMobile boolean false Enable mobile mode
device string - Device preset (e.g., "iPhone 14 Pro")

Output Options

Parameter Type Default Description
format string "png" "png", "jpeg", or "webp"
quality number 80 JPEG/WebP quality (1-100)
fullPage boolean false Capture full scrollable page
omitBackground boolean false Transparent background (PNG only)

Scroll Position

Capture screenshots at a specific scroll position. This is useful for capturing content below the fold or specific sections of long pages.

Parameter Type Default Description
scrollPosition.y number 0 Vertical scroll position in pixels (0-50000)
scrollPosition.behavior string "instant" "instant" or "smooth" scroll animation

Note: scrollPosition cannot be used together with fullPage: true. Use either full page capture or scroll position, not both.

Element Selection

Parameter Type Description
selector string CSS selector for element to capture
padding number Padding around selected element (px)
hideSelectors string[] Elements to hide before capture
clip object Clip region {x, y, width, height}

Wait Options

Parameter Type Description
waitFor.selector string Wait for element to appear
waitFor.timeout number Max wait time in ms (default: 5000)
delay number Fixed delay before capture (ms)
waitUntil string "load", "domcontentloaded", "networkidle"

Cookie Consent

Automatically accept cookie consent banners before capturing. This feature is enabled by default and supports major consent management platforms like OneTrust, CookieBot, and common patterns.

Parameter Type Default Description
acceptCookies boolean true Automatically click cookie accept buttons
cookieAcceptTimeout number 2500 Timeout in ms to wait for cookie banner (0-10000)

Supported platforms: OneTrust, CookieBot, Quantcast, Osano, and common GDPR/cookie consent patterns. The feature uses graceful degradation - if no banner is found, the screenshot proceeds normally.

Examples

Basic Screenshot

Request 
{
  "url": "https://example.com",
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "format": "png"
}

Full Page with JPEG Output

Request 
{
  "url": "https://example.com/blog",
  "fullPage": true,
  "format": "jpeg",
  "quality": 90
}

Capture Specific Element

Request 
{
  "url": "https://example.com",
  "selector": ".hero-section",
  "padding": 20,
  "hideSelectors": [".cookie-banner", ".popup"]
}

Mobile Device Emulation

Request 
{
  "url": "https://example.com",
  "device": "iPhone 14 Pro",
  "fullPage": true
}

Screenshot at Scroll Position

Request 
{
  "url": "https://example.com/long-page",
  "scrollPosition": {
    "y": 1500,
    "behavior": "instant"
  },
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

Scroll with Delay for Lazy Content

Request 
{
  "url": "https://example.com/lazy-content",
  "scrollPosition": {
    "y": 2000,
    "behavior": "smooth"
  },
  "waitOptions": {
    "waitUntil": "networkidle0",
    "delay": 2000
  }
}

Disable Cookie Auto-Accept

Request 
{
  "url": "https://example.com",
  "acceptCookies": false
}

Cookie Accept with Extended Timeout

Request 
{
  "url": "https://gdpr-heavy-site.eu",
  "acceptCookies": true,
  "cookieAcceptTimeout": 5000
}

Wait for Dynamic Content

Request 
{
  "url": "https://example.com/dashboard",
  "waitFor": {
    "selector": "[data-loaded='true']",
    "timeout": 10000
  },
  "waitUntil": "networkidle"
}

Custom HTML Rendering

Request 
{
  "html": "<html><body><h1>Hello World</h1></body></html>",
  "viewport": { "width": 800, "height": 600 },
  "format": "png"
}

Response

Success Response 
{
  "success": true,
  "data": {
    "id": "scr_abc123def456",
    "url": "https://cdn.screencraft.dev/s/abc123.png",
    "width": 1920,
    "height": 1080,
    "format": "png",
    "size": 245678,
    "created_at": "2025-12-27T10:30:00Z",
    "expires_at": "2025-12-28T10:30:00Z"
  }
}

Device Presets

Available device presets for mobile emulation:

Device Width Height Scale
iPhone 14 Pro 393 852 3
iPhone 14 Pro Max 430 932 3
iPad Pro 12.9" 1024 1366 2
Pixel 7 412 915 2.625
Galaxy S23 Ultra 384 824 3

See the full list of available devices in your dashboard.