# Shotbot

> Screenshot-as-a-service API. Capture any public URL as JPEG, PNG, WebP, AVIF, or PDF. Running since 2008.

## APIv2 endpoints

- Submit capture: POST https://api.shotbot.net/capture
- Poll status: GET https://api.shotbot.net/capture/{token}
- Download private capture (one-shot): GET https://api.shotbot.net/capture/{token}/file
- Batch (up to 500 URLs, Pro: 5000): POST https://api.shotbot.net/capture/batch
- Callback (webhook delivery): POST https://api.shotbot.net/capture/callback
- Account status: GET https://api.shotbot.net/account?key={key}

## Machine-readable spec

- OpenAPI 3.1 YAML: https://api.shotbot.net/openapi.yaml
- Interactive reference (Redoc): https://api.shotbot.net/docs

## Authentication

API key passed as `key` field in every JSON POST body. Key format: 12-character hex string.
GET /account accepts `?key=` query-string or `Authorization: Bearer <key>` header.

## Key parameters

- `url` (required): public http/https URL to capture
- `format`: jpg (default, free) | png | webp | avif | pdf (Pro)
- `viewport_width`: 390/768/1280 (free) | custom 280-3840 px (Pro), default 1280
- `output_size`: output image width in px, defaults to viewport_width
- `ratio`: 16:9 (default) | 4:3 | 1:1 | 9:16 | ... (11 ratios)
- `wait`: seconds to wait before capture, 0-30, default 5
- `color_scheme`: "dark" | "light", emulates prefers-color-scheme media query (all users)
- `crop_height`: custom output height in px, cropped from top, max 30000 (Pro only)
- `fullpage`: capture full page height, max 30000 px (boolean)
- `selector`: CSS selector, clips output to matching element (Pro only, non-PDF)
- `cookies`: array of {name, value, domain?, path?}, max 50, injected before navigation (Pro only)
- `private`: bool, result NOT uploaded to CDN; fetch once via GET /capture/{token}/file then deleted (410)
- `callback_url`: HTTPS webhook for async delivery (no polling needed)
- `callback_secret`: shared secret echoed back for webhook verification
- `dismiss_cookies`: "" | "accept" | "reject" (Pro)
- `block_ads`: boolean (Pro)
- `http_auth`: {user, pass} for HTTP Basic Auth (Pro)

## Response tokens

Every successful capture returns a `token` (32-character alphanumeric `[A-Za-z0-9]`).
Poll GET /capture/{token} until status is "done" or "failed".
Public result CDN URL: https://static.shotbot.net/{token[0]}/{token[0..1]}/{token}.{format}
Private result: GET /capture/{token}/file (one-shot, 410 Gone after first download).

## Tiers

Free: jpg only, viewports 390/768/1280, wait max 5 s, 3 concurrent jobs, batch max 500
Shotbot Pro (subscription): all formats, custom viewports 280-3840, wait max 30 s, 15 concurrent, batch max 5000, rendering options (selector, cookies, crop_height, dismiss_cookies, block_ads, http_auth)

## CLI clients

Three single-file CLI wrappers around APIv2 (PHP, Python, Node.js, same flags, same exit codes).
Install Node.js client: curl -fsSL https://api.shotbot.net/cli/node/shotbot -o shotbot && chmod +x shotbot
Install PHP client:     curl -fsSL https://api.shotbot.net/cli/php/shotbot -o shotbot && chmod +x shotbot
Install Python client:  curl -fsSL https://api.shotbot.net/cli/python/shotbot -o shotbot && chmod +x shotbot
Usage: shotbot capture --url=https://example.com [--format=webp] [--viewport=1280] [--wait=10] [--full-page] [--output=./shots/]
JSON output: add --json for machine-parseable responses (token, status, image_url).
Exit codes: 0=success 2=bad-args 3=network 4=api-error 5=waitlisted 6=failed 7=timeout
Config: SHOTBOT_API_KEY env var (CI-friendly) or ~/.shotbot-node-cli/config.json
--output flag saves the file locally and auto-sets private=true (result not on CDN).

## MCP server

Native MCP tool integration for Claude Code, Claude Desktop, Cursor, Windsurf, and other MCP-compatible agents.
HTTP endpoint: https://api.shotbot.net/mcp?key={your_api_key}
Claude Code (one command, no Node.js required): claude mcp add --scope user shotbot --transport http "https://api.shotbot.net/mcp?key=your-key"
Claude Desktop / Cursor / Windsurf: add {"mcpServers":{"shotbot":{"url":"https://api.shotbot.net/mcp?key=your-key"}}} to your MCP config file.
Tools: capture, get_status, batch, account_status
Transport: HTTP (streamable). API key passed as ?key= query param.
README: https://api.shotbot.net/shotbot-mcp/README.md
Guide: https://www.shotbot.net/claude-code-screenshots/

## Documentation and resources

- EN API docs: https://www.shotbot.net/screenshot-api/
- FR API docs: https://www.shotbot.fr/api-capture-ecran/
- Code examples (PHP/Python/Node/Go/cURL/Ruby/Batch): https://www.shotbot.net/screenshot-api-examples/
- Live API tester: https://www.shotbot.net/screenshot-api-tester/
- CLI tools: https://www.shotbot.net/cli-tools/
- For AI agents: https://www.shotbot.net/for-ai-agents/
- Screenshots with Claude Code: https://www.shotbot.net/claude-code-screenshots/
- Service status: https://ping.shotbot.fr/
- FAQ: https://www.shotbot.fr/faq/
- Pro subscription: https://www.shotbot.fr/pro/