API Reference

Authentication

Authentication is optional. Set API_KEYS in your environment to enable it. When enabled, every request must include a valid key.

Via header (recommended)

X-Api-Key: your-api-key

Via query param

?api_key=your-api-key

API keys are redacted from all server logs.

Error Responses

All errors return JSON with a consistent shape:

{ "error": "ERROR_CODE", "message": "Human-readable explanation" }

HTTP	Code	Cause
400	VALIDATION_ERROR	Missing or invalid parameters
400	INVALID_URL	URL is malformed or not http/https
401	UNAUTHORIZED	Missing or invalid API key
403	BLOCKED	URL targets private/loopback address (SSRF)
408	TIMEOUT	Page load exceeded `SCREENSHOT_TIMEOUT_MS`
422	NAVIGATION_FAILED	Browser could not load the page
422	SELECTOR_NOT_FOUND	`selector`, `click`, or `wait_for_selector` not found
429	RATE_LIMITED	Too many requests — see `retryAfter` in response
503	POOL_EXHAUSTED	All browser slots busy, retry later

Rate Limiting

Limits are applied per API key, or per IP when auth is disabled. Default: 60 requests/minute. Configure via MAX_REQUESTS_PER_MINUTE.

        # 429 response body

        { "error": "RATE_LIMITED", "message": "Too many requests. Limit: 60 per minute.", "retryAfter": "23s" }

Caching

Every screenshot is cached by a SHA-256 hash of all capture parameters. Identical requests are served from cache without launching a browser. The X-Cache response header tells you whether the response was cached.

X-Cache: HIT — served from cache

X-Cache: MISS — fresh capture, now cached

Use cache=false to bypass cache. TTL is set via CACHE_TTL_SECONDS (default: 3600).

GET /screenshot

Capture a screenshot of a URL or rendered HTML. Returns a binary image, base64 JSON, or metadata JSON depending on response_type.

Source

Parameter	Type	Default	Description
url	string	—	Page URL to capture (http/https only). Required unless `html` is provided required*
html	string	—	Base64-encoded HTML to render instead of a URL optional

Viewport

Parameter	Type	Default	Description
width	integer	1280	Viewport width in px (100–3840)
height	integer	800	Viewport height in px (100–2160)
device_scale_factor	float	1	Device pixel ratio. Use `2` for retina
viewport_mobile	boolean	false	Enable mobile emulation (touch events, mobile meta tag)

Capture

Parameter	Type	Default	Description
format	enum	png	`png` · `jpeg` · `webp` · `pdf`
quality	integer	80	1–100. Applies to jpeg and webp only
full_page	boolean	false	Capture the full scrollable height of the page
omit_background	boolean	false	Transparent background (PNG only)
selector	string	—	CSS selector — capture only that element
clip_x / clip_y	integer	0	Clip region top-left corner in px
clip_width / clip_height	integer	0	Clip region size (0 = disabled)
image_width / image_height	integer	0	Resize output (0 = no resize). Preserves aspect ratio

Timing

Parameter	Type	Default	Description
delay	integer ms	0	Extra wait after page load (max 10000ms)
wait_until	enum	networkidle2	`load` · `domcontentloaded` · `networkidle0` · `networkidle2`
wait_for_selector	string	—	Wait for this CSS selector to appear before capturing

Emulation

Parameter	Type	Default	Description
dark_mode	boolean	false	Force `prefers-color-scheme: dark`
reduced_motion	boolean	false	Enable `prefers-reduced-motion: reduce`
media_type	enum	screen	`screen` or `print`
timezone	string	—	IANA timezone, e.g. `America/New_York`
geolocation_latitude	float	—	Latitude (−90 to 90)
geolocation_longitude	float	—	Longitude (−180 to 180)
geolocation_accuracy	integer m	100	Geolocation accuracy radius in meters
user_agent	string	—	Custom User-Agent string
proxy	string	Coming soon	Managed proxy profile or explicit proxy endpoint for network-origin targeting (not live yet)
proxy_country	string	Coming soon	ISO country code for proxy-based local screenshots, e.g. `DE` or `US` (not live yet)
proxy_region	string	Coming soon	Region or state code for proxy targeting when supported (not live yet)
proxy_city	string	Coming soon	City-level proxy targeting when supported (not live yet)

Injection & Interaction

Parameter	Type	Description
headers	JSON string	Extra HTTP request headers, e.g. `{"Authorization":"Bearer token"}`
cookies	JSON string	Cookies array, e.g. `[{"name":"s","value":"abc","domain":"example.com"}]`
styles	string	CSS to inject into the page before capture
scripts	string	JavaScript to inject into the page before capture
hide_selectors	string	Comma-separated CSS selectors to hide (sets `display:none`)
click	string	CSS selector to click before capturing

Blocking

Parameter	Default	Description
block_ads	false	Block ads (powered by Ghostery)
block_trackers	false	Block trackers (powered by Ghostery)
block_cookie_banners	false	Block cookie consent banners
block_requests	—	Comma-separated URL patterns to block, e.g. `analytics.js,hotjar.com`

PDF Options

Parameter	Default	Description
pdf_print_background	false	Include background graphics in PDF
pdf_landscape	false	Landscape orientation
pdf_paper_format	a4	`a4` · `a3` · `a2` · `a1` · `letter` · `legal` · `tabloid`

Content Extraction

When extract_content=true, the response includes a content field alongside the image. Only available with response_type=json or base64.

Parameter	Default	Description
extract_content	false	Extract page body as text
content_format	markdown	`html` · `markdown` · `text`

Metadata Extraction

When metadata=true, the response includes a metadata object with title, OG tags, and favicon. Cache is bypassed for metadata requests.

"metadata": {
  "title": "Page Title",
  "description": "Meta description",
  "og_title": "OG Title",
  "og_image": "https://example.com/og.png",
  "og_description": "OG description",
  "favicon": "https://example.com/favicon.ico",
  "http_status": 200
}
      

Async / Webhook

Parameter	Default	Description
async	false	Return `202` with `job_id` immediately, process in background
webhook_url	—	POST result JSON to this URL when the job completes

Cache & Response

Parameter	Default	Description
cache	true	Set to `false` to force a fresh screenshot
response_type	image	`image` — binary · `json` — metadata only · `base64` — image in JSON

Response Headers

Header	Description
X-Cache	`HIT` if served from cache, `MISS` if freshly captured
Cache-Control	`public, max-age=<CACHE_TTL_SECONDS>`
ETag	Cache key SHA-256 hash

POST /batch

Capture screenshots of up to 10 URLs in a single request. Processed in parallel. Each URL is captured independently — if one fails, others still complete.

Request Body (JSON)

Field	Type	Default	Description
urls	string[]	—	Array of URLs (1–10) required
format	enum	png	Output format for all URLs
width / height	integer	1280 / 800	Viewport dimensions
quality	integer	80	Compression quality (jpeg/webp)
full_page	boolean	false	Full page capture
response_type	enum	base64	`base64` · `paths` · `image_urls`

Response

{
  "total": 3,
  "results": [
    { "url": "https://...", "format": "png", "cached": false, "image": "data:image/png;base64,..." },
    { "url": "https://...", "error": "Navigation timeout" }  // per-URL error
  ]
}
      

SSRF protection applies to all URLs upfront. If any URL targets a private address, the entire request returns 403.

GET /diff

Pixel-level visual comparison between two URLs. Both pages are captured in parallel, then compared with pixelmatch. Changed pixels are highlighted in red in the diff image.

Query Parameters

Parameter	Default	Description
before	—	URL of the "before" state required
after	—	URL of the "after" state required
width / height	1280 / 800	Viewport dimensions for both captures
threshold	0.1	Sensitivity (0–1). Lower = more sensitive to subtle changes
response_type	image	`image` — PNG · `json` — stats only · `base64` — image + stats

JSON Response (`response_type=json`)

{
  "before": "https://myapp.com/v1",
  "after": "https://myapp.com/v2",
  "width": 1280,  "height": 800,
  "changed_pixels": 14320,
  "total_pixels": 1024000,
  "diff_percent": 1.40,
  "has_changes": true
}
      

GET /jobs/:id

Check the status of an async screenshot job. Jobs expire from memory after 1 hour.

Job Statuses

pending → processing → done | failed

Success

{
  "id": "550e8400...",
  "status": "done",
  "createdAt": "2024-01-15T12:00:00Z",
  "completedAt": "2024-01-15T12:00:03Z",
  "result": {
    "url": "https://example.com/",
    "format": "png",
    "storagePath": "storage/..."
  }
}
          

Failure

{
  "id": "550e8400...",
  "status": "failed",
  "createdAt": "2024-01-15T12:00:00Z",
  "completedAt": "2024-01-15T12:00:05Z",
  "error": "Page load timed out after 30000ms"
}
          

GET /health

Returns service health — no auth required.

{
  "status": "ok",
  "browserPool": { "size": 3, "available": 2 },
  "cache": "redis"
}
      

Environment Variables

Variable	Default	Description
PORT	3000	Port to listen on
API_KEYS	—	Comma-separated API keys. Empty = auth disabled
SAVE_TO_DISK	false	Save screenshots to disk and return path instead of binary
LOCAL_STORAGE_PATH	./storage	Directory for saved screenshots
STORAGE_TYPE	local	`local` or `s3`
REDIS_URL	—	Redis connection URL. Falls back to in-memory if not set
CACHE_TTL_SECONDS	3600	Cache TTL in seconds
BROWSER_MAX_CONCURRENT	3	Browser pool size. Each instance uses ~300MB RAM
SCREENSHOT_TIMEOUT_MS	30000	Max page load time in ms
MAX_REQUESTS_PER_MINUTE	60	Rate limit per API key/IP
CORS_ORIGIN	—	Restrict CORS, e.g. `https://yourdomain.com`. Omit to allow all
S3_BUCKET	—	S3 bucket name
S3_ENDPOINT	—	S3 endpoint URL (for MinIO, Cloudflare R2, etc.)
S3_REGION	us-east-1	S3 region
S3_ACCESS_KEY / S3_SECRET_KEY	—	S3 credentials

MCP Server

SnapshotFlow now exposes MCP directly from the backend at https://api.snapshotflow.com/mcp. This is the primary remote MCP endpoint for agents and MCP-compatible clients.

Recommended setup: connect your client to the hosted MCP endpoint on api.snapshotflow.com. A local stdio MCP wrapper still exists for development, but most users should use the server MCP endpoint.

Remote MCP endpoint

https://api.snapshotflow.com/mcp

How it works

The MCP transport is served by the backend itself.
The MCP tools call the same screenshot engine and storage layer as the HTTP API.
Available tools are screenshot, batch_screenshot, visual_diff, and check_job.

Configure a local stdio wrapper (optional)

If your MCP client expects a local process, you can still use the bundled stdio wrapper. Example for ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "screenshot": {
      "command": "node",
      "args": ["/absolute/path/to/screenshot-backend/dist/mcp.js"],
      "env": {
        "SCREENSHOT_API_URL": "https://api.snapshotflow.com",
        "SCREENSHOT_API_KEY": "your-api-key"
      }
    }
  }
}
      

Point SCREENSHOT_API_URL at your backend, for example https://api.snapshotflow.com. If your API requires authentication, set SCREENSHOT_API_KEY too.

Available MCP tools

Tool	Description
screenshot	Capture one URL or base64 HTML. Returns an image plus metadata, content, and cache info.
batch_screenshot	Capture up to 10 URLs in one request. Returns one image result per URL.
visual_diff	Compare two URLs visually and return a diff image with change statistics.
check_job	Check the status of an async screenshot job created by the HTTP API.

Run locally in development

        npm run dev
        
        npm run mcp:dev

The local stdio wrapper does not embed the browser pool or Fastify app. It forwards tool calls to the running screenshot backend via SCREENSHOT_API_URL, so keep the HTTP API online while your MCP client is connected.

Docker

Full stack with Redis

API_KEYS=mykey123 docker compose up

Custom pool size

BROWSER_MAX_CONCURRENT=5 API_KEYS=mykey123 docker compose up

The Docker image uses system Chromium (PUPPETEER_SKIP_DOWNLOAD=true) and runs as a non-root node user. shm_size: 1gb is set in docker-compose to prevent Chrome crashes on complex pages.

Coming Soon roadmap

Video capture — GET /video

Record a page interaction as an MP4 or WebM file. Supports scroll/click action replay, configurable duration and FPS, and the same response_type convention as /screenshot — stream the binary directly or get a storage path / async job_id.

Planned Parameters

Parameter	Type	Default	Description
url	string	—	Page to record required
duration	integer s	5	Recording duration in seconds (max 60)
fps	integer	25	Frames per second
format	enum	mp4	`mp4` or `webm`
width / height	integer	1280 / 800	Viewport dimensions
actions	JSON array	—	Scroll / click actions to replay during recording, e.g. `[{"type":"scroll","y":800,"delay":1000}]`

The response will follow the same response_type convention — stream the binary file or return a JSON with a storage path / async job_id.