API Reference

Complete reference for all getSnap.dev endpoints.

Complete endpoint index

30 operations across 27 unique paths. All endpoints live under https://api.getsnap.dev and require an X-API-Key header unless noted. The tables below link to detailed reference sections on this page, the dedicated teams doc and referrals doc, or the fully interactive Swagger UI.

Capture (7)

Signed render links (2)

Scheduled captures (7)

Teams (11) — full reference at /docs/teams.html

Personal billing (2)

Growth (1) — full reference at /docs/referrals.html

Ops (5)

The authoritative source for every endpoint's request / response schema is the Swagger UI. It's generated from the same Zod schemas that validate every request, so if the docs and the server ever disagree, Swagger UI is right. This page walks through the highest-value capture endpoints in narrative form with runnable examples; jump to Swagger for exhaustive per-field docs.

Capture Screenshot

Captures a screenshot or PDF of a URL or HTML content. Returns either a CDN URL or raw binary data.

Request Headers

Request Body

HTML Rendering Example

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body style=\"padding:40px;font-family:sans-serif\"><h1>Hello World</h1><p>Generated by getSnap.dev</p></body></html>",
    "viewport_width": 1200,
    "viewport_height": 630,
    "format": "png"
  }'

Retina Screenshot Example

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com",
    "device_scale_factor": 2,
    "format": "png"
  }'

Custom JS Injection Example

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "js": "document.querySelector(\".sidebar\").style.display = \"none\";"
  }'

Authenticated Page with Cookies

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": [
      {"name": "session_id", "value": "abc123", "domain": "app.example.com"},
      {"name": "auth_token", "value": "xyz789"}
    ],
    "headers": {"Authorization": "Bearer your-token"}
  }'

Localized Screenshot

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://google.com",
    "locale": "de-DE",
    "timezone": "Europe/Berlin"
  }'

Response (URL mode)

{
  "url": "https://getsnap-screenshots.fra1.cdn.digitaloceanspaces.com/screenshots/a1b2c3d4/req_abc123.png",
  "cached": false,
  "request_id": "req_abc123",
  "response_time_ms": 2340
}

Additional fields appear conditionally:

• extracted_text — present when extract_text: true
• extracted_html — present when extract_html: true
• extracted_metadata — present when extract_metadata: true. Contains title, favicon, open_graph (map), fonts (array), http_status, http_status_text, http_headers.
• slices — present when full_page_slices: true. Array of { index, offset_y, width, height, url } objects; each slice is uploaded as its own object on the CDN.
• s3_key and s3_bucket — present when s3_upload was provided and the upload succeeded.

Response (Binary mode)

Response (Webhook mode)

{
  "request_id": "req_abc123",
  "status": "pending",
  "message": "Screenshot is being captured. Result will be POSTed to your webhook_url.",
  "status_url": "https://api.getsnap.dev/v1/screenshot/req_abc123"
}

When the screenshot is ready, getSnap.dev will POST to your webhook_url:

{
  "event": "screenshot.completed",
  "request_id": "req_abc123",
  "url": "https://getsnap-screenshots.fra1.cdn.digitaloceanspaces.com/screenshots/a1b2c3d4/req_abc123.png",
  "cached": false,
  "response_time_ms": 6500
}

Batch Capture

Capture screenshots of multiple URLs in a single request. Processes URLs sequentially and returns all results. Supports up to 100 URLs per batch.

Request Body

Example

curl -X POST https://api.getsnap.dev/v1/batch \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://stripe.com",
      "https://github.com",
      "https://example.com"
    ],
    "format": "png",
    "device_scale_factor": 2,
    "block_ads": true
  }'

Response (Synchronous)

{
  "batch_id": "batch_abc123",
  "count": 3,
  "succeeded": 3,
  "failed": 0,
  "response_time_ms": 12500,
  "results": [
    {
      "url": "https://cdn.../screenshots/abc/req_1.png",
      "source_url": "https://stripe.com",
      "cached": false,
      "request_id": "req_1"
    },
    {
      "url": "https://cdn.../screenshots/def/req_2.png",
      "source_url": "https://github.com",
      "cached": false,
      "request_id": "req_2"
    },
    {
      "url": "https://cdn.../screenshots/ghi/req_3.png",
      "source_url": "https://example.com",
      "cached": false,
      "request_id": "req_3"
    }
  ]
}

Response (Async with webhook_url)

{
  "batch_id": "batch_abc123",
  "status": "pending",
  "count": 3,
  "message": "Batch capture started. Results will be POSTed to your webhook_url.",
  "status_url": "https://api.getsnap.dev/v1/screenshot/batch_abc123"
}

Screenshot Status

Check the status of an async webhook screenshot or batch request. Only accessible with the same API key that created the request.

Response

{
  "request_id": "req_abc123",
  "status": "completed",
  "created_at": "2026-08-25T12:00:00",
  "completed_at": "2026-08-25T12:00:07",
  "result": {
    "event": "screenshot.completed",
    "url": "https://getsnap-screenshots.fra1.cdn.digitaloceanspaces.com/screenshots/a1b2c3d4/req_abc123.png"
  }
}

Possible status values: pending, processing, completed, failed.

Error Responses

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": { "url": ["Either 'url' or 'html' must be provided"] }
}

{
  "error": "quota_exceeded",
  "message": "Monthly limit of 100 screenshots reached. Upgrade your plan.",
  "used": 100,
  "limit": 100
}

{
  "error": "capture_failed",
  "message": "Navigation timeout exceeded",
  "request_id": "req_abc123"
}

Capture Scrolling Video

Records a smoothly-scrolling capture of a URL as an MP4 or GIF. Uses Chrome DevTools' Page.screencast protocol for high-fps frame sampling and encodes the result with ffmpeg.

Request Headers

Request Body

Example

curl -X POST https://api.getsnap.dev/v1/video \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com",
    "format": "mp4",
    "duration_ms": 8000,
    "fps": 20,
    "viewport_width": 1280,
    "viewport_height": 720,
    "quality": 75
  }'

Response (URL mode)

{
  "url": "https://getsnap-screenshots.fra1.cdn.digitaloceanspaces.com/videos/ONE9iLdU/vid_ONE9iLdUbWKeijB6.mp4",
  "request_id": "vid_ONE9iLdUbWKeijB6",
  "format": "mp4",
  "duration_ms": 8000,
  "frame_count": 160,
  "fps": 20,
  "bytes": 2109440,
  "credits_charged": 8,
  "response_time_ms": 10432
}

Response (Webhook mode)

{
  "request_id": "vid_ONE9iLdUbWKeijB6",
  "status": "pending",
  "message": "Video is being captured. Result will be POSTed to your webhook_url.",
  "credits_reserved": 8
}

When the video is ready, getSnap.dev will POST a video.completed event to your webhook (or video.failed on error) using the same delivery, retry, and HMAC-signature semantics as the schedules webhook.

Create Scheduled Capture

Creates a cron-driven scheduled capture. On each tick the worker runs takeScreenshot(), uploads to the CDN, optionally POSTs to your webhook, and logs a row in schedule_runs.

Request Body

Example

curl -X POST https://api.getsnap.dev/v1/schedules \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "morning traffic dashboard",
    "cron": "0 9 * * MON-FRI",
    "timezone": "Europe/Berlin",
    "options": {
      "url": "https://dash.example.com",
      "format": "png",
      "full_page": true,
      "viewport_width": 1600
    },
    "webhook_url": "https://my-app.com/webhooks/getsnap",
    "webhook_secret": "a-strong-shared-secret-abcd1234"
  }'

Response

{
  "id": "sched_SVVnySRhW-xbqYrE",
  "name": "morning traffic dashboard",
  "cron": "0 9 * * MON-FRI",
  "timezone": "Europe/Berlin",
  "options": { "url": "https://dash.example.com", "format": "png", "full_page": true, "viewport_width": 1600 },
  "webhook_url": "https://my-app.com/webhooks/getsnap",
  "has_webhook_secret": true,
  "is_active": true,
  "next_run_at": "2026-09-21T07:00:00.000Z",
  "created_at": "2026-09-20 07:05:26",
  "updated_at": "2026-09-20 07:05:26"
}

List Scheduled Captures

Returns every schedule owned by the API key that made the request. Sorted newest-first.

Response

{
  "count": 2,
  "schedules": [ /* Schedule objects, same shape as Create response */ ]
}

Fetch Scheduled Capture

Returns one schedule by ID. 404 if it doesn't exist or isn't owned by the requesting key.

Update Scheduled Capture

Every top-level field is optional. Provide only what changes. Editing cron, timezone, or is_active is fully synchronized with the underlying queue: the old repeatable job is removed and a new one registered atomically.

To clear webhook_url or webhook_secret, pass an empty string.

Example (pause a schedule)

curl -X PATCH https://api.getsnap.dev/v1/schedules/sched_SVVnySRhW-xbqYrE \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Delete Scheduled Capture

Deletes the schedule, unregisters it from the queue, and drops its schedule_runs history.

{ "deleted": true, "id": "sched_SVVnySRhW-xbqYrE" }

Trigger Scheduled Capture Now

Fires a one-off ad-hoc run of the schedule without touching the cron. Useful for testing a new schedule end-to-end before waiting for the next tick.

{
  "schedule_id": "sched_SVVnySRhW-xbqYrE",
  "status": "queued",
  "message": "Capture queued; result will be delivered via webhook (if configured) and appear in /runs."
}

List Schedule Runs

Returns the last 100 execution records for a schedule (older rows are pruned automatically to keep history bounded).

{
  "schedule_id": "sched_SVVnySRhW-xbqYrE",
  "count": 3,
  "runs": [
    {
      "id": "run_mX4RpcnmpBLYhdXd",
      "status": "completed",
      "result_url": "https://getsnap-screenshots.fra1.cdn.digitaloceanspaces.com/screenshots/scheduled/…/run_mX4RpcnmpBLYhdXd.png",
      "error": null,
      "response_ms": 1373,
      "webhook_status": 200,
      "started_at": "2026-09-20 07:09:04",
      "completed_at": "2026-09-20 07:09:05"
    }
  ]
}

Create Render Link

Generate a signed render link URL. Use the returned URL in <img> tags, OG meta tags, or anywhere that accepts an image URL. The link serves screenshots via GET requests without exposing your API key.

Request Body

Accepts the same parameters as POST /v1/screenshot (url, html, format, viewport_width, etc.).

Response

{
  "render_url": "https://api.getsnap.dev/v1/render?url=https%3A%2F%2Fexample.com&format=png&signature=abc123&key=pk_...",
  "message": "Use this URL in <img> tags or anywhere that accepts an image URL."
}

Render (Signed URL)

Serves a screenshot from a signed render link. Redirects to the CDN URL. No authentication header needed — the signature in the URL verifies the request. Generated by POST /v1/render-link.

Get Usage

Returns your current billing period usage statistics.

Request Headers

Response

{
  "period": "2026-08",
  "used": 847,
  "limit": 5000,
  "plan": "starter",
  "remaining": 4153
}

Health Check

Returns the API service status. No authentication required.

Response

{
  "status": "ok",
  "timestamp": "2026-08-22T12:00:00.000Z",
  "version": "1.0.0"
}