API Documentation

Everything you need to capture screenshots programmatically.

1 Quick Start

Get your first screenshot in under a minute. Sign up to get your API key - no credit card required.

cURL 
curl "https://api.snapforge.techyowls.io/v1/screenshot?url=https://example.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output screenshot.png

That's it! The API returns a PNG image by default. Cached requests return in ~50ms!

Base URL

https://api.snapforge.techyowls.io

All API endpoints are relative to this base URL.

2 Authentication

All requests require an API key sent via the X-API-Key header.

Header Format 
X-API-Key: sk_live_xxxxxxxxxxxxx

Get your API key: Sign up for free - no credit card required. 50 screenshots/day included!

Take Screenshot

GET /v1/screenshot

Captures a screenshot of the specified URL. Returns image binary (default) or JSON with CDN URL.

Parameters

Core Parameters

Parameter Type Default Description
url* string - URL to capture (must be valid HTTP/HTTPS)
format string png png, jpeg, webp, or pdf
width integer 1280 Viewport width (1-3840)
height integer 720 Viewport height (1-2160)
full_page boolean false Capture entire scrollable page
delay integer 0 Wait ms before capture (0-30000)
quality integer - JPEG/WebP quality (1-100)
response_type string binary binary (image) or json (CDN URL)

Caching Parameters

Parameter Type Default Description
cache string true Use cache: true or false
max_age integer 86400 Max cache age in seconds (3600-604800)

PDF Parameters

Parameter Type Default Description
page_size string A4 A4, Letter, Legal, Tabloid
orientation string portrait portrait or landscape
margin string normal none, small, normal, large
print_background boolean true Include background colors/images

Auto-Clean Parameters (Free)

Parameter Type Default Description
clean boolean false Remove common annoyances (all below)
clean_cookies boolean false Remove cookie consent banners
clean_chat boolean false Remove chat widgets
clean_popups boolean false Remove modal popups

* Required parameter

Blocking Parameters Starter+

Parameter Type Default Description
block_ads boolean false Block advertisements
block_trackers boolean false Block tracking scripts
block_cookie_banners boolean false Block cookie consent banners via request interception
basic_auth JSON - HTTP Basic Auth: {"username":"x","password":"y"}

Authentication Parameters Pro+

Pro Plan Required: Screenshot authenticated pages with session cookies or custom headers. Perfect for dashboards, admin panels, and private content.

Parameter Type Default Description
cookies JSON - Session cookies: [{"name":"x","value":"y"}]
headers JSON - Custom HTTP headers: {"Authorization":"Bearer x"}
stealth boolean false Bypass bot detection (Cloudflare, etc.)
stealth_level string standard basic, standard, or aggressive
headers_scope string same-origin Where to send custom headers: same-origin, same-site, all

Graceful Degradation

Auth parameters (cookies, headers, basic_auth) use graceful degradation:

  • If you don't have the required plan, the request still succeeds
  • The auth parameters are simply ignored
  • A header indicates which features were ignored: X-SnapForge-Features-Ignored

Device Frames

Parameter Type Default Description
frame string - Add device frame: browser, browser-dark, iphone-14, macbook-pro, ipad-pro, window-macos, window-windows

Customer S3 Storage Business

Business Plan Required: Upload screenshots directly to your own S3-compatible bucket (AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO).

Parameter Type Default Description
s3_bucket string - Your S3 bucket name
s3_region string - AWS region (e.g., us-east-1)
s3_access_key string - Your S3 access key
s3_secret_key string - Your S3 secret key
s3_endpoint string - Custom endpoint for R2/MinIO/DO Spaces
s3_path string - Path prefix in bucket (e.g., screenshots/)

Caching

SnapForge uses a two-tier caching system (Redis + Cloudflare R2 CDN) for blazing fast responses.

How It Works

  • cache=true (default): Check cache first. If HIT, return from CDN (~50ms). If MISS, capture and cache.
  • cache=false: Skip cache, capture fresh screenshot. Still updates cache in background.

Response Headers

X-Cache: HIT        # Served from cache
X-Cache: MISS       # Fresh capture, now cached
X-Cache: BYPASS     # cache=false was used
X-Cache-Age: 3600   # Cache age in seconds

Pro tip: For frequently accessed URLs, cached responses return in ~50ms compared to ~2.5s for fresh captures!

Response

Binary Response (default)

Returns the image directly. Cache HITs return 302 redirect to CDN.

Headers (Cache MISS) 
HTTP/2 200 OK
Content-Type: image/png
X-Cache: MISS
[binary image data]
Headers (Cache HIT) 
HTTP/2 302 Found
Location: https://pub-xxx.r2.dev/screenshots/abc123.png
X-Cache: HIT
X-Cache-Age: 1234

JSON Response

When response_type=json, returns a CDN URL.

JSON Response 
{
  "url": "https://pub-xxx.r2.dev/screenshots/abc123.png",
  "cached": true,
  "cache_age": 1234,
  "format": "png",
  "width": 1280,
  "height": 720
}

Error Codes

All errors follow a consistent JSON format:

Error Response 
{
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid"
  },
  "request_id": "req_abc123"
}
Code HTTP Description
INVALID_CREDENTIALS 401 Invalid or missing API key
RATE_LIMITED 429 Too many requests
INVALID_PARAMS 400 Parameter validation failed
SSRF_BLOCKED 403 URL blocked (internal/private IP)
REQUEST_TIMEOUT 504 Screenshot took too long
QUEUE_TIMEOUT 503 Service busy, retry later
SCREENSHOT_FAILED 500 Failed to capture screenshot

Rate Limits

Plan Screenshots/day Requests/min Price
Free 50 5 $0
Starter 500 15 $7/mo
Pro 3,000 30 $29/mo
Business 10,000 60 $49/mo

Rate Limit Headers

X-RateLimit-Limit: 15
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1701620400

Code Examples

cURL

Basic Screenshot 
curl "https://api.snapforge.techyowls.io/v1/screenshot?url=https://github.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output github.png

JavaScript (Node.js)

Node.js with fetch 
const params = new URLSearchParams({
  url: 'https://github.com',
  width: 1280,
  height: 720,
  format: 'png'
});

const response = await fetch(
  `https://api.snapforge.techyowls.io/v1/screenshot?${params}`,
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync('screenshot.png', buffer);

Python

Python with requests 
import requests

response = requests.get(
    'https://api.snapforge.techyowls.io/v1/screenshot',
    params={
        'url': 'https://github.com',
        'width': 1280,
        'height': 720,
    },
    headers={'X-API-Key': 'YOUR_API_KEY'}
)

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

Get CDN URL (JSON Response)

cURL - JSON response 
curl "https://api.snapforge.techyowls.io/v1/screenshot?\
url=https://github.com&\
response_type=json" \
  -H "X-API-Key: YOUR_API_KEY"

# Returns:
# {"url":"https://pub-xxx.r2.dev/...","cached":true,...}

Force Fresh Screenshot

Bypass cache 
curl "https://api.snapforge.techyowls.io/v1/screenshot?\
url=https://github.com&\
cache=false" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output fresh.png

# X-Cache header will be: BYPASS

Screenshot with Cookies Pro+

Capture authenticated dashboard 
# URL-encode the cookies JSON
COOKIES='[{"name":"session","value":"abc123","domain":".example.com"}]'
ENCODED=$(echo "$COOKIES" | jq -sRr @uri)

curl "https://api.snapforge.techyowls.io/v1/screenshot?\
url=https://app.example.com/dashboard&\
cookies=$ENCODED" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output dashboard.png

Screenshot with Authorization Header Pro+

Capture protected API page 
# URL-encode the headers JSON
HEADERS='{"Authorization":"Bearer eyJhbGciOiJIUzI1NiIs..."}'
ENCODED=$(echo "$HEADERS" | jq -sRr @uri)

curl "https://api.snapforge.techyowls.io/v1/screenshot?\
url=https://admin.example.com&\
headers=$ENCODED" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output admin.png

Screenshot with Basic Auth Starter+

Capture staging site 
# URL-encode the basic_auth JSON
AUTH='{"username":"admin","password":"secret"}'
ENCODED=$(echo "$AUTH" | jq -sRr @uri)

curl "https://api.snapforge.techyowls.io/v1/screenshot?\
url=https://staging.example.com&\
basic_auth=$ENCODED" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output staging.png

HTML Render API Starter+

POST /v1/render

Render HTML content directly to screenshot without hosting it. Perfect for generating images from templates, invoices, charts, or dynamic content.

Request Body (JSON) 
{
  "html": "<html><body><h1>Hello World</h1></body></html>",
  "base_url": "https://example.com",
  "width": 1280,
  "height": 720,
  "format": "png",
  "full_page": false,
  "frame": "browser"
}

Request Body Parameters

Parameter Type Description
html* string HTML content to render (required)
base_url string Base URL for relative links/assets
width integer Viewport width (default: 1280)
height integer Viewport height (default: 720)
format string png, jpeg, webp
full_page boolean Capture full scrollable content
frame string Add device frame (see Device Frames)
response_type string binary or json
cURL Example 
curl "https://api.snapforge.techyowls.io/v1/render" \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello</h1>","width":800,"height":600}' \
  --output render.png

Batch API Pro+

Process multiple URLs in a single request with webhook notification when complete. Perfect for capturing many pages efficiently.

Create Batch

POST /v1/batch
Request Body 
{
  "urls": [
    { "url": "https://example.com" },
    { "url": "https://github.com", "options": { "width": 1920 } }
  ],
  "webhook_url": "https://your-server.com/webhook",
  "default_options": {
    "format": "png",
    "width": 1280,
    "height": 720
  }
}

Other Batch Endpoints

Method Endpoint Description
GET /v1/batch/:id Get batch status and results
DELETE /v1/batch/:id Cancel a running batch
GET /v1/batches List all your batches
Webhook Payload 
{
  "batch_id": "abc123",
  "status": "completed",
  "total": 10,
  "succeeded": 9,
  "failed": 1,
  "results": [
    { "url": "https://example.com", "status": "success", "screenshot_url": "..." }
  ],
  "duration_ms": 15000
}

Best Practices

Leverage caching

Default cache=true returns cached screenshots in ~50ms. Only use cache=false when you need fresh content.

Use JSON response for frontend apps

Set response_type=json to get a CDN URL. Display it directly in <img src="..."> for best performance.

Add delay for dynamic content

For SPAs or pages with JavaScript animations, use delay=2000 to wait for content to load.

Use clean parameters

Remove distracting elements with clean=true to hide cookie banners, chat widgets, and popups.

Ready to get started?

Sign up for free - no credit card required. 50 screenshots/day included!

Get Free API Key