All screenshot endpoints require authentication (Authorization: Bearer YOUR_API_KEY). Responses include base64-encoded image data. Use "responseFormat": "binary" to get raw image bytes instead.

POST /v1/screenshot — Basic Screenshot

Request Body

Parameter	Type	Default	Description
url	string	—	Required. The URL to screenshot.
fullPage	boolean	`false`	Capture the full scrollable page height.
width	number	`1280`	Viewport width in pixels (100–5000).
height	number	`720`	Viewport height in pixels (100–5000).
format	string	`"png"`	Image format: `png`, `jpeg`, or `jpg`.
quality	number	—	JPEG quality (1–100). Only used with `jpeg`/`jpg` format.
waitFor	number	—	Milliseconds to wait after page load (0–60000).
selector	string	—	CSS selector — screenshot only this element.
actions	array	—	Browser actions to perform before screenshotting (click, type, scroll, etc.).
stealth	boolean	`false`	Enable stealth mode for Cloudflare-protected pages.
scrollThrough	boolean	`false`	Scroll through the page before capturing (triggers lazy-loaded content).
headers	object	—	Custom HTTP headers to send with the request.
responseFormat	string	`"json"`	Set `"binary"` to receive raw image bytes instead of base64 JSON.

Response

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "screenshot": "data:image/png;base64,iVBORw0KGgo...",
    "metadata": {
      "sourceURL": "https://example.com",
      "format": "png",
      "width": 1280,
      "height": 720,
      "fullPage": false
    }
  }
}

POST /v1/screenshot/filmstrip

Scrolls through the page and captures evenly-spaced frames, useful for previewing long pages.

Request Body

Parameter	Type	Default	Description
url	string	—	Required.
frames	number	`6`	Number of frames to capture (2–12).
width	number	`1280`	Viewport width (100–5000).
height	number	`720`	Viewport height (100–5000).
format	string	`"png"`	Image format.
stealth	boolean	`false`	Stealth mode.

Response

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "format": "png",
    "frameCount": 6,
    "frames": [
      { "index": 0, "scrollY": 0, "screenshot": "data:image/png;base64,..." },
      { "index": 1, "scrollY": 720, "screenshot": "data:image/png;base64,..." }
    ]
  }
}

POST /v1/screenshot/viewports

Capture the same URL at multiple viewport sizes in a single request. Perfect for responsive design testing.

Request Body

Parameter	Type	Default	Description
url	string	—	Required.
viewports	array	—	Required. Array of `{"width": N, "height": N, "label": "..."}` objects. Max 6.
fullPage	boolean	`false`	Full-page capture for all viewports.
format	string	`"jpeg"`	Image format.
quality	number	—	JPEG quality (1–100).

Response

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "format": "jpeg",
    "viewports": [
      { "label": "mobile", "width": 375, "height": 812, "screenshot": "data:image/jpeg;base64,..." },
      { "label": "desktop", "width": 1440, "height": 900, "screenshot": "data:image/jpeg;base64,..." }
    ]
  }
}

POST /v1/screenshot/diff

Compare two URLs pixel-by-pixel and return a diff image highlighting changes.

Request Body

Parameter	Type	Default	Description
url1	string	—	Required. First URL (baseline).
url2	string	—	Required. Second URL (comparison). Must differ from url1.
width	number	`1280`	Viewport width.
height	number	`720`	Viewport height.
fullPage	boolean	`false`	Full-page comparison.
threshold	number	`0.1`	Per-pixel difference threshold (0–1). Higher = more tolerant.

Response

{
  "success": true,
  "data": {
    "diff": "data:image/png;base64,...",
    "diffPixels": 4821,
    "totalPixels": 921600,
    "diffPercent": 0.52,
    "dimensions": { "width": 1280, "height": 720 }
  }
}

POST /v1/screenshot/design-audit

Screenshot each major section of a page (e.g. <section> elements) individually. Useful for component-level visual audits.

Request Body

Parameter	Type	Default	Description
url	string	—	Required.
selector	string	`"section"`	CSS selector for elements to capture individually.
rules	object	—	Custom audit rules object.
scrollThrough	boolean	`false`	Scroll before capturing to trigger lazy-loaded content.

Response

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "format": "jpeg",
    "sections": [
      { "index": 0, "tag": "section", "id": "hero", "className": "hero", "top": 0, "height": 600, "screenshot": "..." },
      { "index": 1, "tag": "section", "id": "features", "className": "features", "top": 600, "height": 400, "screenshot": "..." }
    ]
  }
}

POST /v1/screenshot/design-analysis

AI-powered analysis of a page's design — colors, typography, layout structure, and UX observations.

Request Body

Parameter	Type	Default	Description
url	string	—	Required.
selector	string	—	Analyze only a specific element.
width	number	`1280`	Viewport width.
stealth	boolean	`false`	Stealth mode for protected pages.

Response

{
  "success": true,
  "data": {
    "url": "https://example.com",
    "analysis": {
      "colors": ["#18181B", "#FFFFFF", "#3B82F6"],
      "typography": { "headingFont": "Inter", "bodyFont": "Inter" },
      "layout": "single-column with hero, features grid, and CTA",
      "observations": ["Strong contrast ratio", "Consistent spacing", "Mobile-first layout"]
    }
  }
}

GET /v1/design-compare

Compare the design quality of two URLs and receive a similarity score with improvement suggestions.

Query Parameters

Parameter	Type	Description
url	string	Required. Subject URL to evaluate.
ref	string	Required. Reference URL (benchmark design).
width	number	Viewport width (100–5000).
height	number	Viewport height (100–5000).

POST /v1/screenshot/animation

Capture a sequence of frames at regular intervals to visualize animations, transitions, or scrolling behavior.

Request Body

Parameter	Type	Default	Description
url	string	—	Required.
frames	number	`6`	Number of frames to capture (1–30).
intervalMs	number	`500`	Milliseconds between frames (50–10000).
scrollTo	number	—	Scroll to this Y position before starting capture.
selector	string	—	Capture only this element.
format	string	`"jpeg"`	Image format.

POST /v1/review

Convenience endpoint that runs mobile + tablet + desktop screenshots AND a design audit in one request.

Request Body

Parameter	Type	Description
url	string	Required.
rules	object	Custom design audit rules.
selector	string	CSS selector for the audit.

Examples

curl -X POST https://api.webpeel.dev/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webpeel.dev",
    "fullPage": true,
    "width": 1440,
    "format": "jpeg",
    "quality": 85
  }'

curl -X POST https://api.webpeel.dev/v1/screenshot/viewports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webpeel.dev",
    "viewports": [
      { "width": 375, "height": 812, "label": "mobile" },
      { "width": 768, "height": 1024, "label": "tablet" },
      { "width": 1440, "height": 900, "label": "desktop" }
    ],
    "format": "jpeg",
    "quality": 80
  }'

curl -X POST https://api.webpeel.dev/v1/screenshot/diff \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url1": "https://staging.example.com",
    "url2": "https://production.example.com",
    "width": 1280,
    "height": 800,
    "threshold": 0.05
  }'

# Runs mobile + tablet + desktop + design audit in one request (4 credits)
curl -X POST https://api.webpeel.dev/v1/review \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webpeel.dev"
  }'