# SnapshotFlow Screenshot API — Agent Skill

Capture any webpage as a PNG, JPEG, WebP, or PDF. Run visual diffs between two URLs, batch-capture up to 10 pages in parallel, and extract page content as Markdown. SnapshotFlow is a hosted API: there is nothing to install or run.

## Base URL

`https://api.snapshotflow.com`

## Authentication

Every request needs an API key. Requests without one return `401 UNAUTHORIZED`.

The user creates an account at https://dashboard.snapshotflow.com/#/register (300 free screenshots, no credit card) and creates an API key in the dashboard. Pass it in one of two ways:
- Header: `X-Api-Key: <key>` (preferred)
- Query param: `?api_key=<key>`

To get access on the user's behalf without a manually created key, follow https://snapshotflow.com/auth.md

## Capture a Screenshot

```
GET /screenshot?url=<url>[&format=png|jpeg|webp|pdf][&full_page=true][&width=1280][&height=800]
```

Key options:
- `format` — `png` (default), `jpeg`, `webp`, `pdf`
- `full_page=true` — capture the full scrollable height
- `dark_mode=true` — prefers-color-scheme: dark
- `selector` — capture only this CSS element
- `delay` — extra wait in ms after load (max 10000)
- `wait_for_selector` — wait for a CSS selector to appear
- `extract_content=true` — add `content` (Markdown by default) to the JSON response
- `metadata=true` — add page title, description, og_image, favicon, and HTTP status
- `async=true` — returns `{ job_id, status }` immediately (202); poll `/jobs/:id`
- `response_type` — `image` (binary, default) | `json` | `base64`

## Batch Screenshots

```
POST /batch
Content-Type: application/json

{
  "urls": ["https://example.com", "https://github.com"],
  "format": "png",
  "response_type": "base64"
}
```

Up to 10 URLs in a single request. Each result includes either `image` (base64) or `error`.

## Visual Diff

```
GET /diff?before=<url>&after=<url>[&threshold=0.1][&response_type=json]
```

Returns a highlighted diff image or JSON stats:
```json
{ "diff_percent": 0.14, "changed_pixels": 1420, "has_changes": true }
```

## Check Async Job

```
GET /jobs/:id
```

Returns `{ id, status, result }`. Statuses: `pending` → `processing` → `done` | `failed`.

## Health

```
GET /health
```

Service health check. No auth required.

## MCP Integration

Remote MCP endpoint (Streamable HTTP): `https://api.snapshotflow.com/mcp`

```json
{
  "mcpServers": {
    "snapshotflow": {
      "url": "https://api.snapshotflow.com/mcp"
    }
  }
}
```

Authentication is OAuth 2.1 with PKCE: on first connect the MCP client opens a browser, the user signs in, and the client receives a Bearer token automatically. API keys are not accepted on `/mcp`.

MCP tools: `screenshot`, `batch_screenshot`, `visual_diff`, `extract_text`, `check_job`.

## Error Codes

All errors return `{ "error": "CODE", "message": "..." }`.

| Code | HTTP | Meaning |
|------|------|---------|
| `VALIDATION_ERROR` | 400 | Invalid parameter |
| `INVALID_URL` | 400 | Malformed or blocked URL |
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
| `BLOCKED` | 403 | SSRF-protected private IP |
| `TIMEOUT` | 408 | Page load timed out |
| `RATE_LIMITED` | 429 | Too many requests |
| `POOL_EXHAUSTED` | 503 | No browser slots available |
