Getting Started

Everything you need to capture your first screenshot in under a minute.

Authentication

All API requests require an API key passed in the X-API-Key header. You can get a free API key by signing up at getsnap.dev.

X-API-Key: sk_live_YOUR_API_KEY

Note: Your API key starts with sk_live_ for production or sk_test_ for testing. Keep your key secret — never expose it in client-side code.

Your First Request

Capture a screenshot with a single POST request:

curl -X POST https://api.getsnap.dev/v1/screenshot \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png"
  }'

That's it. The API returns a CDN URL to your screenshot:

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

Response Format

By default, the API uploads the screenshot to CDN and returns a URL. You can also get the raw binary:

URL Response (default)

Set "response_type": "url" (or omit it). Returns a JSON object with the CDN URL. The screenshot is stored for 24 hours.

Binary Response

Set "response_type": "binary". Returns the raw image/PDF bytes directly with the appropriate Content-Type header.

Response Headers

Every response includes helpful headers:

Header	Description
X-Request-Id	Unique request identifier for debugging
X-Cache	`HIT` if served from cache, `MISS` if freshly captured
X-Credits-Remaining	Screenshots remaining in your billing period
X-Response-Time	Server processing time

Rate Limits

Rate limits are applied per API key using a sliding window. When exceeded, the API returns 429 Too Many Requests.

Plan	Requests/min	Monthly Screenshots
Free	5	100
Starter	30	5,000
Pro	60	25,000
Business	120	100,000

Error Handling

All errors return a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable description",
  "request_id": "req_xyz123"
}

Common Error Codes

Status	Code	Meaning
400	validation_error	Invalid request body or parameters
401	unauthorized	Missing or invalid API key
402	quota_exceeded	Monthly screenshot limit reached
429	rate_limited	Too many requests per minute
500	capture_failed	Screenshot capture failed (timeout, invalid URL, etc.)

Tip: Always check for 402 responses in production. Implement exponential backoff for 429 responses.

Caching

Identical requests (same URL + same options) are automatically cached for 24 hours. Cached responses are free and don't count against your quota. Check the X-Cache: HIT header to confirm a cached response.

Base URL

https://api.getsnap.dev

All endpoints are versioned under /v1/. When we release breaking changes, we'll increment the version and keep old versions running for at least 12 months.