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

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