# SnapRender - Complete API Documentation

> Screenshot API for developers. Capture any website as PNG, JPEG, WebP, or PDF with a single HTTP GET request.

## Quick Start

Sign up free at https://app.snap-render.com/auth/signup to get an API key (starts with `sk_live_`).

```bash
curl -o screenshot.png "https://app.snap-render.com/v1/screenshot?url=https://example.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Authentication

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

```
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Get your free API key at https://app.snap-render.com/auth/signup (no credit card required).

## Endpoints

### GET /v1/screenshot

Capture a screenshot of any URL.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| url | string | (required) | URL to capture (http or https) |
| format | string | png | Output format: png, jpeg, webp, pdf |
| width | integer | 1280 | Viewport width in pixels (320-3840) |
| height | integer | 800 | Viewport height in pixels (200-10000) |
| full_page | string | false | Capture entire scrollable page |
| quality | integer | 90 | Image quality for JPEG/WebP (1-100) |
| delay | integer | 0 | Milliseconds to wait after page load (0-10000) |
| dark_mode | string | false | Emulate prefers-color-scheme: dark |
| block_ads | string | true | Block advertisements and trackers |
| block_cookie_banners | string | true | Remove cookie consent banners |
| device | string | - | Device preset: iphone_14, iphone_15_pro, pixel_7, ipad_pro, macbook_pro |
| hide_selectors | string | - | CSS selectors to hide (comma-separated) |
| click_selector | string | - | CSS selector to click before capture |
| user_agent | string | - | Custom user agent string |
| cache | string | true | Use cached result if available |
| cache_ttl | integer | 86400 | Cache TTL in seconds (0-2592000) |
| response_type | string | binary | Response format: binary (raw image) or json (base64 data URI) |

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

**Response (json, recommended for AI agents):**
```json
{
  "url": "https://example.com",
  "format": "png",
  "width": 1280,
  "height": 800,
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "size": 45320,
  "cache": "MISS",
  "responseTime": "1234ms",
  "remainingCredits": 499
}
```

**Response Headers:**
- `X-Cache`: HIT or MISS
- `X-Response-Time`: Total time (e.g., "1234ms")
- `X-Remaining-Credits`: Screenshots remaining this period
- `X-Request-Id`: Unique request ID for support

### GET /v1/screenshot/info

Check cache status without capturing. Does not count against quota.

**Parameters:** url, format, width, height (same as /v1/screenshot)

**Response:**
```json
{
  "url": "https://example.com",
  "cached": true,
  "cachedAt": "2026-03-08T12:00:00Z",
  "expiresAt": "2026-03-09T12:00:00Z",
  "size": 45320
}
```

### GET /v1/usage

Get current month usage statistics.

**Response:**
```json
{
  "plan": "free",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "usage": {
    "screenshots_used": 42,
    "screenshots_limit": 500,
    "screenshots_remaining": 458
  }
}
```

### GET /v1/usage/daily

Get daily usage breakdown for the past N days.

**Parameters:** days (integer, 1-90, default 30)

**Response:**
```json
{
  "days": 30,
  "data": [
    { "date": "2026-03-01", "count": 15 },
    { "date": "2026-03-02", "count": 27 }
  ]
}
```

### GET /health

Health check (no authentication required).

## Code Examples

### curl

```bash
# Basic screenshot
curl -o screenshot.png \
  "https://app.snap-render.com/v1/screenshot?url=https://example.com" \
  -H "X-API-Key: YOUR_API_KEY"

# Mobile screenshot (iPhone 15 Pro)
curl -o mobile.png \
  "https://app.snap-render.com/v1/screenshot?url=https://example.com&device=iphone_15_pro" \
  -H "X-API-Key: YOUR_API_KEY"

# Full page PDF
curl -o page.pdf \
  "https://app.snap-render.com/v1/screenshot?url=https://example.com&format=pdf&full_page=true" \
  -H "X-API-Key: YOUR_API_KEY"

# JSON response (for AI agents)
curl "https://app.snap-render.com/v1/screenshot?url=https://example.com&response_type=json" \
  -H "X-API-Key: YOUR_API_KEY"

# Dark mode, no ads, custom viewport
curl -o dark.png \
  "https://app.snap-render.com/v1/screenshot?url=https://example.com&dark_mode=true&block_ads=true&width=1920&height=1080" \
  -H "X-API-Key: YOUR_API_KEY"

# Force fresh capture (skip cache)
curl -o fresh.png \
  "https://app.snap-render.com/v1/screenshot?url=https://example.com&cache=false" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Node.js (SDK)

```javascript
import { SnapRender } from 'snaprender';

const client = new SnapRender('YOUR_API_KEY');

// Basic screenshot
const screenshot = await client.screenshot('https://example.com');

// With options
const screenshot = await client.screenshot('https://example.com', {
  format: 'jpeg',
  fullPage: true,
  darkMode: true,
  device: 'iphone_15_pro',
});
```

Install: `npm install snaprender`

### Python (SDK)

```python
from snaprender import SnapRender

client = SnapRender("YOUR_API_KEY")

# Basic screenshot
screenshot = client.screenshot("https://example.com")

# With options
screenshot = client.screenshot("https://example.com",
    format="jpeg",
    full_page=True,
    dark_mode=True,
    device="iphone_15_pro",
)
```

Install: `pip install snaprender`

### Node.js (fetch)

```javascript
const response = await fetch(
  'https://app.snap-render.com/v1/screenshot?url=https://example.com&response_type=json',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.image); // data:image/png;base64,...
```

### Python (requests)

```python
import requests

response = requests.get(
    'https://app.snap-render.com/v1/screenshot',
    params={'url': 'https://example.com', 'response_type': 'json'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()
print(data['image'])  # data:image/png;base64,...
```

## Device Presets

| Preset | Resolution | Scale | Description |
|--------|-----------|-------|-------------|
| iphone_14 | 390x844 | 3x | iPhone 14 |
| iphone_15_pro | 393x852 | 3x | iPhone 15 Pro |
| pixel_7 | 412x915 | 2.625x | Google Pixel 7 |
| ipad_pro | 1024x1366 | 2x | iPad Pro 12.9" |
| macbook_pro | 1512x982 | 2x | MacBook Pro 14" |

## Error Codes

| Code | Status | Description |
|------|--------|-------------|
| INVALID_URL | 400 | URL is malformed or uses unsupported protocol |
| BLOCKED_URL | 400 | URL targets localhost, private IPs, or cloud metadata |
| INVALID_DEVICE | 400 | Unknown device preset |
| VALIDATION_ERROR | 400 | Invalid request parameters |
| UNAUTHORIZED | 401 | Missing or invalid API key |
| QUOTA_EXCEEDED | 429 | Monthly screenshot limit reached |
| RATE_LIMITED | 429 | Too many requests per minute |
| DOMAIN_RATE_LIMITED | 429 | Too many requests to same domain |
| RENDER_FAILED | 500 | Screenshot capture failed |
| SERVER_ERROR | 500 | Internal server error |

## Rate Limits

Requests per minute and per-domain limits by plan:

| Plan | Monthly Limit | Requests/min | Per Domain/min |
|------|--------------|-------------|----------------|
| Free | 500 | 10 | 5 |
| Starter | 2,000 | 30 | 10 |
| Growth | 10,000 | 60 | 20 |
| Business | 50,000 | 120 | 40 |
| Scale | 200,000 | 300 | 100 |

## Pricing

| Plan | Price | Screenshots/month | All Features |
|------|-------|-------------------|-------------|
| Free | $0 | 500 | Yes |
| Starter | $9/mo | 2,000 | Yes |
| Growth | $29/mo | 10,000 | Yes |
| Business | $79/mo | 50,000 | Yes |
| Scale | $199/mo | 200,000 | Yes |

All plans include every feature. No feature gating. Upgrade or downgrade at any time.

## MCP Server (AI Agent Integration)

SnapRender provides an MCP (Model Context Protocol) server for AI agent frameworks.

- npm package: `@snaprender/mcp-server`
- Endpoint: `https://app.snap-render.com/mcp`
- Supports: Claude, ChatGPT, and any MCP-compatible agent

## Links

- Website: https://snap-render.com
- API Base URL: https://app.snap-render.com
- Documentation: https://app.snap-render.com/docs
- OpenAPI Spec: https://app.snap-render.com/openapi.json
- npm SDK: https://www.npmjs.com/package/snaprender
- PyPI SDK: https://pypi.org/project/snaprender/
- GitHub Integrations: https://github.com/User0856/snaprender-integrations
- Support: support@snap-render.com