API Documentation

Authentication
Screenshot Endpoint
Premium Features
PDF Generation
Device Presets
Error Codes
Rate Limits

Authentication

All API requests require an API key. You can pass your API key in one of three ways:

Query parameter: ?api_key=YOUR_KEY
Header: X-API-Key: YOUR_KEY
Header: Authorization: Bearer YOUR_KEY

Screenshot Endpoint

GET/api/v1/screenshot

POST/api/v1/screenshot

Basic Parameters

Parameter	Type	Default	Description
`url`	string	required	URL to capture
`width`	number	1280	Viewport width (320-3840)
`height`	number	800	Viewport height (240-2160)
`full_page`	boolean	false	Capture full scrollable page
`format`	string	png	Output format: png, jpeg, webp, pdf
`quality`	number	90	Image quality (1-100, jpeg/webp only)
`delay`	number	0	Wait time in ms before capture (0-10000)
`block_ads`	boolean	false	Block advertisements
`block_cookie_banners`	boolean	true	Hide cookie consent popups
`dark_mode`	boolean	false	Emulate dark mode preference
`device_scale_factor`	number	1	Device pixel ratio (1-3)

Example Request (GET)

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&api_key=YOUR_KEY&width=1920&full_page=true"

Example Request (POST)

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1920,
    "full_page": true,
    "device": "desktop",
    "dark_mode": true
  }'

Example Response

{
  "success": true,
  "data": {
    "screenshot_url": "https://r2.shotapi.dev/screenshots/abc123.png",
    "width": 1920,
    "height": 3200,
    "format": "png",
    "file_size": 524288,
    "cached": false
  },
  "usage": {
    "credits_used": 43,
    "credits_limit": 500,
    "credits_remaining": 457
  }
}

Premium Features

The following features are available on paid plans only. Free plan users will receive a 403 error when trying to use these features.

Parameter	Type	Description
`device`	string	Device preset (desktop, mobile, tablet, iphone-14, etc.)
`selector`	string	CSS selector to capture specific element only
`hide_selectors`	string[]	CSS selectors of elements to hide (comma-separated for GET)
`custom_css`	string	Custom CSS to inject into the page (max 10KB)
`custom_js`	string	Custom JavaScript to execute (max 10KB)
`wait_for_selector`	string	Wait for element before capture (10s timeout)
`custom_headers`	object	Custom HTTP headers (POST only)
`user_agent`	string	Custom user agent string
`thumbnail`	object	Generate thumbnail: {width, height}
`extract_html`	boolean	Include page HTML in response
`clip`	object	Crop region: {x, y, width, height}

Example: Capture Specific Element

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "selector": "#main-content",
    "hide_selectors": [".ads", ".cookie-banner", ".popup"]
  }'

Example: Custom CSS Injection

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "custom_css": "body { background: #f0f0f0; } .header { display: none; }"
  }'

Example: Generate Thumbnail

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "thumbnail": { "width": 300, "height": 200 }
  }'

Response includes thumbnail_url in addition to the full screenshot.

PDF Generation

Generate PDF documents from any webpage by setting format=pdf.

Example Request

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&format=pdf&api_key=YOUR_KEY"

PDF Response

{
  "success": true,
  "data": {
    "pdf_url": "https://r2.shotapi.dev/screenshots/abc123.pdf",
    "page_count": 3,
    "format": "pdf",
    "file_size": 156789
  },
  "usage": {
    "credits_used": 44,
    "credits_limit": 500,
    "credits_remaining": 456
  }
}

Device Presets

Use device presets to emulate common device viewports and user agents automatically.

Preset	Width	Height	Scale	Mobile
`desktop`	1920	1080	1x	No
`laptop`	1366	768	1x	No
`tablet`	768	1024	2x	Yes
`tablet-landscape`	1024	768	2x	Yes
`mobile`	375	812	3x	Yes
`mobile-landscape`	812	375	3x	Yes
`iphone-14`	390	844	3x	Yes
`iphone-14-pro-max`	430	932	3x	Yes
`ipad-pro`	1024	1366	2x	Yes
`pixel-7`	412	915	2.625x	Yes

Example: Mobile Screenshot

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&device=iphone-14&api_key=YOUR_KEY"

Error Codes

Code	Status	Description
`MISSING_API_KEY`	401	No API key provided
`INVALID_API_KEY`	401	API key is invalid or revoked
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`CREDITS_EXHAUSTED`	402	Monthly credit limit reached
`PREMIUM_REQUIRED`	403	Feature requires paid plan
`INVALID_URL`	400	URL is invalid or not accessible
`VALIDATION_ERROR`	400	Invalid parameter value
`SCREENSHOT_FAILED`	500	Failed to capture screenshot

Rate Limits

Plan	Requests/min	Screenshots/month	Premium Features
Free	10	500	No
Starter	60	2,500	Yes
Pro	120	10,000	Yes
Business	300	50,000	Yes

Ready to get started? Create a free account or upgrade your plan to unlock premium features.