API Reference

Complete reference for all SnapAPI endpoints.

Capture Screenshot

POST /v1/screenshot

Captures a screenshot or PDF of the specified URL. Returns either a CDN URL or raw binary data.

Request Headers

Header	Type	Description
X-API-Key	string required	Your API key
Content-Type	string required	Must be `application/json`

Request Body

Parameter	Type	Default	Description
url	string required	-	The URL to capture. Must be a valid HTTP/HTTPS URL.
format	string optional	`png`	Output format: `png`, `jpg`, `jpeg`, `webp`, or `pdf`
viewport_width	number optional	`1280`	Viewport width in pixels (320-3840)
viewport_height	number optional	`720`	Viewport height in pixels (200-2160)
full_page	boolean optional	`false`	Capture the entire scrollable page
device	string optional	`desktop`	Device emulation: `desktop`, `mobile`, or `tablet`
delay	number optional	`0`	Wait time in ms before capture (0-10000). Useful for JS-rendered pages.
css	string optional	`""`	Custom CSS to inject before capture (max 10,000 chars)
dark_mode	boolean optional	`false`	Emulate `prefers-color-scheme: dark`
quality	number optional	`80`	Image quality 1-100 (applies to JPG/WebP only)
remove_popups	boolean optional	`true`	AI-powered removal of cookie banners, popups, and overlays
selector	string optional	`""`	CSS selector to capture a specific element instead of the full page
response_type	string optional	`url`	`url` returns CDN link, `binary` returns raw image/PDF bytes

Response (URL mode)

200 OK

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

Response (Binary mode)

200 OK

Returns raw bytes with appropriate Content-Type header (image/png, image/jpeg, image/webp, or application/pdf).

Error Responses

400 Bad Request

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": { "url": ["Must be a valid URL"] }
}

402 Payment Required

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

500 Internal Server Error

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

Get Usage

GET /v1/usage

Returns your current billing period usage statistics.

Request Headers

Header	Type	Description
X-API-Key	string required	Your API key

Response

200 OK

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

Health Check

GET /v1/health

Returns the API service status. No authentication required.

Response

200 OK

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