Quickstart - SnapSnip Docs

Prerequisites

Before continuing, create an API key as described in Authentication, then expose it only to your server-side environment:

export SNAPSNIP_API_KEY="YOUR_API_KEY"

Synchronous capture

This request captures the full page at https://example.com as a PDF and streams the binary response to capture.pdf:

curl --fail \
  --request POST \
  --url "https://api.snapsnip.io/v1/capture" \
  --header "Authorization: Bearer ${SNAPSNIP_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "type": "url",
      "value": "https://example.com"
    },
    "target": {
      "type": "full_page",
      "max_height": 12000
    },
    "output": {
      "format": "pdf"
    },
    "environment": {
      "viewport": {
        "width": 1440,
        "height": 900
      }
    }
  }' \
  --output capture.pdf

A successful synchronous request returns the capture bytes with the selected media type. Errors use the common JSON error response rather than a binary body.

Asynchronous capture

Submit the same request to the asynchronous endpoint:

curl --fail \
  --request POST \
  --url "https://api.snapsnip.io/v1/capture/async" \
  --header "Authorization: Bearer ${SNAPSNIP_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "type": "url",
      "value": "https://example.com"
    },
    "target": {
      "type": "full_page",
      "max_height": 12000
    },
    "output": {
      "format": "png"
    }
  }'

The API returns 202 Accepted:

{
  "capture_id": "abcdefghijklmnopqrstuvwxyz0123456789",
  "status": "queued",
  "status_url": "https://api.snapsnip.io/v1/capture/async/abcdefghijklmnopqrstuvwxyz0123456789",
  "requested_at": "2026-09-21T10:00:00.000Z"
}

Poll capture status

Use status_url, or construct the equivalent account-scoped endpoint:

curl --fail \
  --url "https://api.snapsnip.io/v1/capture/async/${CAPTURE_ID}" \
  --header "Authorization: Bearer ${SNAPSNIP_API_KEY}"

The status progresses through queued, running, and then completed or failed. A retained completed result includes download_url, content_type, size_bytes, and expires_at.

Download the result

Send the API key to the stable Snapsnip download URL and follow its temporary redirect:

curl --fail \
  --location \
  --url "https://api.snapsnip.io/v1/capture/async/${CAPTURE_ID}/download" \
  --header "Authorization: Bearer ${SNAPSNIP_API_KEY}" \
  --output capture.png

The API authenticates the request and redirects to a short-lived downloads.snapsnip.io URL. Standard curl redirect handling does not forward credentials to a different hostname. Do not use --location-trusted.

Next steps

Open the API Reference tab for every capture option and response schema.
Use webhooks on asynchronous requests when polling is undesirable.
Treat capture_id and cloud-storage destination IDs as opaque values.
Retry transient 429, 503, and 504 responses with bounded backoff.

​Prerequisites

​Synchronous capture

​Asynchronous capture

​Poll capture status

​Download the result

​Next steps