Async Screenshots

Enqueue a screenshot job and get the result delivered to your webhook URL. The API returns immediately with 202 Accepted and a job_id.

POST/v1/async/screenshot

Async screenshots require a Growth+ plan and a configured webhook_url.

Parameters

Parameter	Type	Default	Description
`url`*	string	—	The URL to screenshot.
`webhook_url`*	string	—	URL to receive the result via POST when the screenshot is ready.
`width`	number	1280	Viewport width in pixels. Min 320, max 3840.
`height`	number	720	Viewport height in pixels. Min 240, max 2160.
`format`	enum	png	Output format: png, jpeg, or webp.
`quality`	number	80	Compression quality for jpeg/webp. 1–100.
`full_page`	boolean	false	Capture full scrollable page height.
`retina`	boolean	false	Use 2× DPR (HiDPI).
`delay`	number	0	Wait N ms after load. Max 10000.
`wait_until`	enum	load	load, domcontentloaded, or networkidle.
`css`	string	—	Custom CSS to inject before capture.
`js`	string	—	JavaScript to execute before capture.
`dark_mode`	boolean	false	Emulate dark mode.
`block_ads`	boolean	false	Block ads and trackers.
`stealth`	boolean	false	Bypass bot detection.
`device`	string	—	Device preset name.
`bypass_csp`	boolean	false	Disable Content Security Policy.
`proxy`	string	—	Proxy URL (http/https/socks5).
`country`	enum	—	Country for residential proxy: US, GB, DE, JP.

Response (immediate)

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job_abc123",
  "status": "queued",
  "message": "Screenshot job queued. Result will be sent to your webhook URL.",
  "webhook_url": "https://your-app.com/webhook",
  "url": "https://example.com"
}

Webhook delivery

When the screenshot is ready (or fails), SnapSharp sends a POST request to your webhook_url:

Success:

{
  "event": "screenshot.completed",
  "request_id": "550e8400-...",
  "job_id": "job_abc123",
  "url": "https://example.com",
  "success": true,
  "image_base64": "iVBORw0KGgo...",
  "content_type": "image/png",
  "size_bytes": 145230,
  "timestamp": "2026-03-28T12:00:00Z"
}

Failure:

{
  "event": "screenshot.failed",
  "request_id": "550e8400-...",
  "job_id": "job_abc123",
  "url": "https://example.com",
  "success": false,
  "error": "Navigation timeout after 30000ms",
  "timestamp": "2026-03-28T12:00:05Z"
}

Webhook headers:

Header	Description
`X-Request-Id`	Original request ID
`X-Webhook-Signature`	`sha256=<HMAC>` — HMAC-SHA256 of the body, keyed with the `request_id`

Example

curl -X POST https://api.snapsharp.dev/v1/async/screenshot \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "webhook_url": "https://your-app.com/webhooks/screenshot",
    "width": 1440,
    "full_page": true,
    "dark_mode": true
  }'

Errors

Code	Error	Description
400	`validation_error`	Invalid URL or missing `webhook_url`
401	`unauthorized`	Missing or invalid API key
403	`plan_required`	Growth+ plan required
429	`rate_limited`	Rate limit exceeded
503	`queue_unavailable`	Job queue not available — retry later