Snapshot API v1 vs v2 vs v3: Which Endpoint Should You Use?

Snapshot Site exposes three API versions, and new integrations sometimes default to whichever one shows up first in a tutorial rather than the one that actually fits the job. Each version does more than the last, but "more" also means more request fields to think about, so picking the simplest one that covers your use case keeps both the integration and the request payload easier to reason about.

v1/screenshot: The Simple Case

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v1/screenshot \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "url": "https://example.com",
    "format": "png",
    "width": 1280,
    "height": 720,
    "delay": 0,
    "fullSize": false,
    "hideCookie": false
  }'

v1 takes a URL, a format, a viewport size, an optional delay, and whether to hide cookie banners or capture the full page. That is it — no page manipulation, no diffing, no AI analysis. It is the right choice for straightforward capture jobs: documentation screenshots, simple monitoring, asset generation at fixed dimensions like the presets in Emulating iPhone, Android, and Tablet Screens with the Right Width and Height Presets.

Use v1 when you just need a clean screenshot and nothing about the page needs to change before capture.

v2/screenshot: When You Need to Change the Page First

v2 accepts everything v1 does, plus two extra fields:

• hide — a CSS selector for elements to remove before capture (banners, debug toolbars, cookie modals that hideCookie does not catch).
• javascriptCode — arbitrary JavaScript executed on the page before the screenshot is taken.

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v2/screenshot \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "url": "https://example.com",
    "format": "png",
    "width": 1280,
    "height": 720,
    "hide": "#promo-banner",
    "javascriptCode": "document.querySelector(\".modal\")?.remove();"
  }'

Reach for v2 any time the page needs cleanup or a scripted tweak before the capture happens — hiding a staging ribbon, forcing a hover state, removing a support widget that would otherwise cover important content.

v3/analyze: Screenshot Plus AI Insight

v3/analyze layers on top of a capture: waitForDom for more reliable timing on data-heavy pages, plus enableSummary and enableQuality to get an AI-generated summary or quality assessment back alongside the image, instead of just the screenshot itself.

curl --request POST \
  --url https://api.prod.ss.snapshot-site.com/api/v3/analyze \
  --header 'Content-Type: application/json' \
  --header 'x-snapshotsiteapi-key: YOUR_API_KEY' \
  --data '{
    "url": "https://example.com",
    "format": "png",
    "width": 1280,
    "height": 720,
    "waitForDom": true,
    "enableSummary": true,
    "enableQuality": true
  }'

Use v3/analyze when the screenshot itself is not the end goal — when you actually want structured insight about the page, not just a picture of it. See From Screenshot to AI Insights: Turning Web Pages into Actionable Data for what that output looks like in practice.

v3/compare: Two States, One Diff

v3/compare is the odd one out — instead of one URL, it takes before and after, each either a live url or a static imageUrl, plus a threshold for sensitivity. It returns a before image, an after image, a diff image, and mismatch metrics.

Use it whenever the question is "what changed" rather than "what does this look like right now" — release reviews, uptime monitoring against a stored baseline, or CI checks. See Automating Visual Regression Checks in GitHub Actions with the Compare API for a full working example.

A Quick Decision Table

Need	Endpoint
Plain screenshot, no page changes	v1/screenshot
Screenshot with hidden elements or injected JS	v2/screenshot
Screenshot plus AI summary or quality score	v3/analyze
Compare two states or a state against a stored baseline	v3/compare

Starting with the simplest endpoint that solves the actual problem keeps integrations easier to maintain, and every version runs on the same Snapshot Site infrastructure — moving from v1 to v2 or v3 later is an additive change to the request body, not a rewrite.