Developer docs

Screenshotor screenshot API documentation

Authenticate with X-Api-Key, create captures with POST /v1/screenshot, poll or webhook for completion, then download PNG, JPG, or WEBP assets. Standard captures cost 1 credit; AI vision captures cost 2 credits.

Get API key Product overview

Quick start

curl -X POST https://screenshotor.com/api/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"url":"https://example.com","format":"webp","width":1440,"height":900,"fullPage":true}'

Endpoints

Base URL: https://screenshotor.com/api

POSTX-Api-Key

/v1/screenshot

Create a screenshot job. Returns 202 for queued jobs, 200 for cache hits or sync captures.

Screenshot id, status, URL, format, dimensions, and temporary downloadUrl when already complete.

GETX-Api-Key

/v1/screenshot/{id}

Read job status and metadata for one screenshot owned by the API key user.

Status, format, dimensions, file size, temporary downloadUrl when done, and errorMessage when failed.

GETX-Api-Key

/v1/screenshot/{id}/download

Create or return the public temporary download URL for a completed screenshot.

downloadUrl, 48-hour expiry, format, and file size.

GETX-Api-Key

/v1/screenshots?limit=20&offset=0

List recent screenshots for the authenticated user.

Screenshot array plus pagination metadata. limit is capped at 100.

GETX-Api-Key

/v1/usage

Read monthly usage, quota, remaining captures, and daily breakdown.

Plan, quota, period, request counts, cost, remaining quota, and daily breakdown.

Request body parameters

Fields accepted by POST /v1/screenshot. Private and internal URLs are blocked during validation.

Field	Type	Default	Description
url	string URL	required	Target page to capture. DNS and network checks reject private, localhost, link-local, and internal targets.
format	png \| jpg \| webp	webp	Output format. Use webp for compact browser screenshots, png for lossless images, and jpg for photos.
quality	integer	80	Compression quality for lossy image output. Ignored by png.
width	integer	1920	Viewport width in CSS pixels for desktop captures.
height	integer	1080	Viewport height in CSS pixels for desktop captures.
fullPage	boolean	false	Capture the full scrollable page instead of the visible viewport.
device	desktop \| iphone-15 \| ipad	desktop	Device preset. Mobile presets apply mobile viewport, scale factor, and mobile browser behavior.
delay	integer	0	Extra wait after page readiness and before capture. Useful for animations and late-rendered content.
waitForNetworkIdle	boolean	true	Try to wait for network quiet after DOM ready. The API continues if modern long-lived requests prevent idle.
blockResources	boolean	false	Block heavy image, stylesheet, font, and media requests for faster structural captures.
darkMode	boolean	false	Set the browser color scheme preference to dark before loading the page.
userAgent	string	browser default	Override the browser user agent for compatibility testing or crawler-specific page variants.
cookies	array	none	Cookies to set before navigation. Each cookie supports name, value, domain, path, httpOnly, and secure.
bannerBlocking.enabled	boolean	false	Opt in to cookie or consent banner handling for this request only.
bannerBlocking.mode	hide \| reject \| accept	hide	Hide detected banners, click reject-style buttons, or click accept-style buttons before hiding remaining banners.
bannerBlocking.selectors	string[]	[]	Additional CSS selectors for site-specific banners. Defaults already cover common cookie and consent patterns.
aiVision.enabled	boolean	false	When true, sends the completed screenshot image to the configured OpenRouter vision model and stores the text result.
aiVision.prompt	string	required when enabled	Instruction for the vision model, such as Describe the image or Extract the pricing.
webhookUrl	string URL	none	Optional callback URL notified when an async screenshot job finishes.

Example request with AI vision and webhooks

{
  "url": "https://example.com",
  "format": "webp",
  "quality": 80,
  "width": 1440,
  "height": 900,
  "fullPage": false,
  "device": "desktop",
  "delay": 0,
  "waitForNetworkIdle": true,
  "blockResources": false,
  "darkMode": false,
  "bannerBlocking": {
    "enabled": true,
    "mode": "hide",
    "selectors": [
      "#cookie-banner",
      ".consent-modal"
    ]
  },
  "aiVision": {
    "enabled": true,
    "prompt": "Describe the image and extract any visible pricing."
  },
  "webhookUrl": "https://your-app.example/webhooks/screenshots"
}

Endpoints

Request body parameters

Example request with AI vision and webhooks

Related resources