# ScreenshotAPI — Complete API Reference

## Overview
ScreenshotAPI captures pixel-perfect screenshots of any web page via a REST API.
It is designed for AI agent workflows, automation pipelines, and developer tooling.

## Base URL
https://screenshotapi.site/api/v1

## Authentication
All API requests require an API key passed in the x-api-key header.

Example:
  x-api-key: sk_live_your_key_here

Get a free API key (100 screenshots/month): https://screenshotapi.site/signup

## Machine-Readable Specs
- OpenAPI 3.1: https://screenshotapi.site/api/openapi.json
- AI Plugin: https://screenshotapi.site/.well-known/ai-plugin.json
- ARD Catalog: https://screenshotapi.site/.well-known/ai-catalog.json
- Trust Manifest: https://screenshotapi.site/.well-known/trust-manifest.json

---

## POST /api/v1/screenshot

**Purpose:** Capture a screenshot of a web page.

**When to use:** When you need a visual representation of a URL's rendered content.
Use this instead of fetching HTML when you need to see what the page *looks like*
(layout, images, styling) rather than just its content.

### Required Parameters
- url (string): The URL to capture. Must be a valid HTTP/HTTPS URL.

### Optional Parameters
- format (string, default: "png"): Output format. One of: png, jpeg, webp.
- fullPage (boolean, default: false): Capture the entire scrollable page.
- viewport (object): Custom viewport dimensions.
  - width (integer, default: 1280, range: 320-3840)
  - height (integer, default: 800, range: 240-2160)
- device (string, default: "desktop"): Device emulation. One of: desktop, mobile.
- darkMode (boolean, default: false): Render with prefers-color-scheme: dark.
- blockAds (boolean, default: false): Block advertisements. Requires Basic plan+.
- blockCookies (boolean, default: false): Block cookie consent banners. Requires Basic plan+.
- waitUntil (string, default: "load"): Navigation strategy. One of: load, domcontentloaded, networkidle.
- timeout (integer, default: 30000, range: 1000-60000): Max wait time in milliseconds.
- quality (integer, default: 90, range: 1-100): Image quality (JPEG/WebP only).
- extract_metadata (boolean, default: false): Include structured page metadata in response.

### Query Parameters
- base64 (string): When "true", returns JSON with base64-encoded image instead of binary.

### Returns

**Binary mode (default):**
Binary image data with Content-Type header matching the requested format.

**Base64 mode (?base64=true):**
JSON response:
{
  "success": true,
  "request_id": "req_abc123",
  "data": "<base64-encoded-image>",
  "contentType": "image/png",
  "responseTimeMs": 1843,
  "credits_used": 1,
  "credits_remaining": 4999
}

**With extract_metadata=true:**
JSON includes additional page_metadata field:
{
  "page_metadata": {
    "title": "Example Domain",
    "description": "...",
    "og_image": "...",
    "favicon": "...",
    "language": "en",
    "status_code": 200
  }
}

### Response Headers
- X-Request-Id: Unique request identifier for tracing
- X-Response-Time: Server-side processing time
- X-RateLimit-Remaining: Remaining requests in current window
- X-Credits-Remaining: Remaining monthly credits
- X-Credits-Reset: Unix timestamp when credits reset

### Cost
1 credit per successful capture. Failed captures cost 0 credits.

### AI Agent Usage Hints
- For visual QA: use full_page=true with format=png for pixel-perfect comparison
- For thumbnails: set viewport width=600, height=400 and format=webp for small file size
- For social cards: use viewport 1200x630 (OpenGraph dimensions)
- For monitoring: compare sequential captures with image-diff tools
- For batch jobs: use webhook notifications to receive results asynchronously
- For metadata: set extract_metadata=true to get page title, description, and OG data

### Example (most common usage)
POST /api/v1/screenshot
x-api-key: sk_live_...
Content-Type: application/json

{"url": "https://example.com", "format": "png", "fullPage": true, "blockAds": true}

### Error Codes
- 400: Invalid parameters (check error.details for which parameter)
- 401: Missing or invalid API key
- 403: API key deactivated or feature not available on current plan
- 429: Rate limit or quota exceeded (check Retry-After header)
- 500: Rendering failed (retry with longer timeout)

### Structured Error Response
{
  "success": false,
  "request_id": "req_abc123",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "category": "rate_limit",
    "message": "Rate limit exceeded",
    "retryable": true,
    "retry_after_seconds": 5
  }
}

---

## Pricing Tiers

| Plan   | Price     | Screenshots/mo | Rate Limit   |
|--------|-----------|----------------|-------------|
| Free   | $0        | 100            | 10/min       |
| Basic  | $25/mo    | 2,000          | 40/min       |
| Growth | $100/mo   | 10,000         | 80/min       |
| Scale  | $250/mo   | 50,000         | 150/min      |

Annual billing: 20% discount on all paid plans.
All paid plans include a 7-day free trial.

---

## Rate Limiting
Rate limits are enforced per API key on a per-minute basis.
When rate limited, the API returns:
- HTTP 429 status
- Retry-After header with seconds to wait
- X-RateLimit-Remaining: 0
- X-RateLimit-Reset: Unix timestamp

---

## POST /api/v1/smart-screenshot

**Purpose:** AI-driven screenshot capture with browser interaction.

**When to use:** When you need to interact with a page before capturing — dismiss cookie
banners, click buttons, fill forms, scroll to specific content, navigate tabs.
The AI agent sees the page and performs actions autonomously.

**Availability:** Growth and Scale plans only.

### Required Parameters
- url (string): The URL to capture.
- task (string): Plain English description of what the AI should do before capturing.
  Examples: "Click Accept Cookies", "Scroll to the pricing section",
  "Type 'hello' in the search box and press Enter"

### Optional Parameters
- maxSteps (integer, default: 10, range: 1-15): Maximum AI actions before final capture.
- viewport (object): { width: 1280, height: 800 } — custom viewport.
- device (string, default: "desktop"): desktop or mobile.
- format (string, default: "png"): png, jpeg, or webp.
- quality (integer, range: 1-100): Image quality for JPEG/WebP.
- fullPage (boolean, default: false): Capture entire scrollable page.
- darkMode (boolean, default: false): Force dark color scheme.
- blockAds (boolean, default: false): Block advertisements.
- timeout (integer, default: 60000, range: 5000-120000): Max time in ms.

### Returns
JSON response:
{
  "success": true,
  "request_id": "req_abc123",
  "image": "<base64-encoded-image>",
  "contentType": "image/png",
  "responseTimeMs": 12500,
  "credits_used": 10,
  "credits_remaining": 9990,
  "steps_completed": 3,
  "steps": [
    { "step": 1, "action": "click", "description": "Clicking Accept Cookies button" },
    { "step": 2, "action": "scroll", "description": "Scrolling down to pricing" },
    { "step": 3, "action": "done", "description": "Task complete" }
  ]
}

### Cost
- Growth plan: 20 credits per smart screenshot
- Scale plan: 40 credits per smart screenshot

### AI Agent Usage Hints
- Keep task descriptions simple and specific
- Use maxSteps=5 for simple tasks (dismiss popup) to save time
- Use maxSteps=15 for complex multi-step workflows
- The AI sees the actual rendered page — it handles dynamic content, SPAs, and JavaScript
- Combine with extract_metadata for rich page data

---

## Demo Endpoint
POST /api/demo/screenshot
No authentication required. Limited to 5 screenshots per IP per day.
Returns base64-encoded image in JSON response.

---

## Support
- Documentation: https://screenshotapi.site/docs
- Status: https://screenshotapi.site/status
- Email: support@screenshotapi.site