Domain Snapshot API — /api/v1/domain/snapshot

Captures a PNG, JPEG, or PDF snapshot via Playwright. Async mode returns immediately with a job id; sync mode blocks until the screenshot is ready (median 4–8s). Expensive — counts as 5 credits.

• Method GET
• Path /api/v1/domain/snapshot
• Stability STABLE
• Version v2026-05-15
• Summary Headless-browser screenshot of any URL (desktop / tablet / mobile).

Pass these as query-string parameters (or, where indicated, in the request headers). Required params marked required.

• domain (required) — string Full URL or bare domain. Min 3, max 2048 chars.
• device (required) — string, default "desktop" Viewport preset.
• cache — boolean, default true Serve from cache when available (24h TTL).
• fullPage — boolean, default false Capture the full scrollable height instead of just the viewport.
• waitAfterLoad — number, default 0 Extra seconds to wait after `load` before snapshotting (0–30). Useful for animation-heavy pages.
• quality — number, default 90 JPEG/PDF quality (1–100). Ignored for PNG.
• async — boolean, default false Return immediately with a job id; fetch the file once it's ready.
• format — string, default "png" Output file format.
• viewportW — number Override viewport width (320–3840).
• viewportH — number Override viewport height (320–2160).
• blockAds — boolean, default false Inject a hosts-file ad-blocker before navigation.
• dismissConsent — boolean, default false Auto-click GDPR / cookie consent banners.
• userAgent — string Override the browser UA. Max 500 chars.

All successful responses follow the standard `{ success: true, data: {...} }` envelope. Notable fields on the data object for this endpoint:

• data.url — string CDN-backed URL for the captured asset (PNG/JPEG/PDF).
• data.jobId — string Present in async mode — poll `/api/v1/domain/snapshot?jobId=…`.
• data.metadata — object Viewport, device, byte size, capture time.

Truncated but representative example for a real lookup:

{
  "success": true,
  "data": {
    "url": "https://cdn.domainscan.in/snap/github.com-desktop.png",
    "metadata": {
      "device": "desktop",
      "viewport": {
        "w": 1440,
        "h": 900
      },
      "bytes": 184321,
      "tookMs": 4200
    }
  }
}

Errors return HTTP status codes paired with stable machine-readable codes. Match on the code field rather than the human-readable message.

• 400 INVALID_URL Domain failed parsing.
• 504 NAVIGATION_TIMEOUT Page took longer than 30s to load.
• 503 BROWSER_UNAVAILABLE Playwright pool exhausted — retry.

Patterns we recommend when integrating this endpoint:

• Always pass `device` explicitly — defaults can change.
• Use `async=true` in batch jobs; sync ties up an HTTP connection for 4–8s.
• Pair `dismissConsent=true` with `waitAfterLoad=2` for EU sites.

• How long is the CDN URL valid? 7 days. After that, re-run the snapshot.
• Can I capture authenticated pages? Not yet. Login-cookie support is on the roadmap.