API Documentation — GrabShot.dev

Authentication

All API requests require an API key. Pass it as a query parameter or Authorization header:

# Query parameter
GET /v1/screenshot?url=example.com&apiKey=gs_your_key

# Authorization header (preferred)
GET /v1/screenshot?url=example.com
Authorization: Bearer gs_your_key

💡 For testing, use the demo key: sk_demo_123456

Quick Start

Take your first screenshot in 10 seconds:

curl "https://grabshot.dev/v1/screenshot?url=https://github.com&apiKey=sk_demo_123456" \
  --output screenshot.png

Add a device frame:

curl "https://grabshot.dev/v1/screenshot?url=https://github.com&frame=browser&apiKey=sk_demo_123456" \
  --output framed.png

GET /v1/screenshot

Capture a screenshot of any URL with extensive customization options.

Parameters

Parameter	Type	Default	Description
url	string	—	required URL to capture
width	integer	1280	Viewport width in pixels
height	integer	720	Viewport height in pixels
format	string	png	Output format: `png`, `jpeg`, `webp`
quality	integer	80	Image quality (1-100, jpeg/webp only)
fullPage	boolean	false	Capture the full scrollable page
device	string	desktop	Viewport preset: `desktop`, `mobile`, `tablet`
darkMode	boolean	false	Force dark mode via prefers-color-scheme
delay	integer	0	Wait ms after page load before capture
selector	string	—	CSS selector to capture a specific element
frame	string	none	Device frame: `none`, `browser`, `iphone`, `macbook`
retina	boolean	false	Capture at 2x resolution
blockAds	boolean	false	Block common ad/tracker domains
cleanup	boolean	false	🤖 AI-powered removal of popups, cookie banners, chat widgets
json	boolean	false	Return JSON with base64 image instead of binary

Response

By default, returns the image binary with appropriate Content-Type header. With json=true:

{
  "success": true,
  "image": "data:image/png;base64,iVBOR...",
  "width": 1280,
  "height": 720,
  "format": "png",
  "took": 2340
}

POST /v1/register

Create an account and get your API key.

curl -X POST https://grabshot.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response:

{
  "success": true,
  "user": { "id": 1, "email": "[email protected]", "plan": "free" },
  "apiKey": "gs_abc123..."
}

GET /v1/account

View your account info and usage stats. Requires authentication.

curl https://grabshot.dev/v1/account \
  -H "Authorization: Bearer gs_your_key"

API Key Management

POST /v1/keys

Generate an additional API key (max 5 per account).

curl -X POST https://grabshot.dev/v1/keys \
  -H "Authorization: Bearer gs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

DELETE /v1/keys/:id

Revoke an API key.

curl -X DELETE https://grabshot.dev/v1/keys/2 \
  -H "Authorization: Bearer gs_your_key"

Device Frames

Wrap your screenshots in beautiful device mockups. Perfect for marketing materials, social media, and documentation.

frame=browser

Minimal browser chrome with traffic lights and URL bar

frame=iphone

iPhone frame with notch and home indicator

frame=macbook

MacBook Pro frame with screen and base

🤖 AI Cleanup

Our AI-powered cleanup uses Google Gemini Vision to detect and remove visual clutter before taking the final screenshot:

Cookie consent banners
Chat widgets (Intercom, Crisp, etc.)
Newsletter signup popups
App download banners
GDPR/privacy overlays

curl "https://grabshot.dev/v1/screenshot?url=https://nytimes.com&cleanup=true&apiKey=gs_your_key" \
  --output clean.png

⚡ Cleanup adds ~2-3 seconds to capture time due to the AI analysis pass.

Dark Mode

Capture any website in dark mode. Works with sites that support prefers-color-scheme: dark.

curl "https://grabshot.dev/v1/screenshot?url=https://github.com&darkMode=true&apiKey=gs_your_key" \
  --output dark.png

Rate Limits

Plan	Monthly Limit	Rate	Price
Free	100	60/min	$0
Starter	1,000	60/min	$9/mo
Pro	10,000	60/min	$29/mo
Business	50,000	60/min	$79/mo

Error Handling

All errors return JSON with a success: false field:

{
  "success": false,
  "error": "Invalid API key"
}

Status	Meaning
400	Missing or invalid parameters
401	Invalid or missing API key
429	Rate limit or monthly quota exceeded
500	Screenshot capture failed

Code Examples

Node.js

const fetch = require('node-fetch');
const fs = require('fs');

const url = `https://grabshot.dev/v1/screenshot`
  + `?url=https://github.com`
  + `&frame=browser&darkMode=true`
  + `&apiKey=YOUR_API_KEY`;

const res = await fetch(url);
const buffer = await res.buffer();
fs.writeFileSync('screenshot.png', buffer);

Python

import requests

response = requests.get("https://grabshot.dev/v1/screenshot", params={
    "url": "https://github.com",
    "frame": "browser",
    "darkMode": "true",
    "apiKey": "YOUR_API_KEY"
})

with open("screenshot.png", "wb") as f:
    f.write(response.content)

cURL

# Basic screenshot
curl "https://grabshot.dev/v1/screenshot?url=https://example.com&apiKey=YOUR_KEY" -o shot.png

# iPhone frame + dark mode + AI cleanup
curl "https://grabshot.dev/v1/screenshot?url=https://stripe.com&frame=iphone&darkMode=true&cleanup=true&apiKey=YOUR_KEY" -o shot.png

# Full page, retina, JPEG
curl "https://grabshot.dev/v1/screenshot?url=https://tailwindcss.com&fullPage=true&retina=true&format=jpeg&quality=90&apiKey=YOUR_KEY" -o shot.jpg