Back to Home

API Documentation

Complete reference for the ScreenshotAPI endpoint.

Endpoint

POST
/api/v1/screenshot

Returns the screenshot as binary image data (PNG, JPEG, or WebP) with the appropriate Content-Type header. Add ?base64=true query parameter to receive a JSON response with base64-encoded image data.

Authentication

Include your API key in the x-api-key request header.

x-api-key: sk_live_your_api_key_here

Request Parameters

Send as JSON in the request body.

ParameterTypeRequiredDescription
urlstring
Required
The URL of the website to capture. Must be a valid HTTP/HTTPS URL.
fullPageboolean
Optional
Capture the full scrollable page. Default: false
viewportobject
Optional
{ width: number, height: number }. Default: { width: 1280, height: 800 }
devicestring
Optional
"desktop" or "mobile". Default: "desktop"
darkModeboolean
Optional
Enable dark mode rendering. Default: false
blockAdsboolean
Optional
Block advertisements. Requires Basic plan or higher.
blockCookiesboolean
Optional
Block cookie consent banners. Requires Basic plan or higher.
waitUntilstring
Optional
"load", "domcontentloaded", or "networkidle". Default: "load"
timeoutnumber
Optional
Max wait time in ms (1000-60000). Default: 30000
formatstring
Optional
"png", "jpeg", or "webp". Default: "png"
qualitynumber
Optional
Image quality (1-100). Only for JPEG/WebP.

Code Examples

curl -X POST https://screenshotapi.site/api/v1/screenshot \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "fullPage": true,
    "format": "png",
    "viewport": { "width": 1280, "height": 800 }
  }' \
  --output screenshot.png

Rate Limits & Quotas

Rate limits and monthly quotas vary by plan:

PlanMonthly QuotaRate LimitOverage
Free10010/min-
Basic2,00040/min$0.009/screenshot
Growth10,00080/min$0.006/screenshot
Scale50,000150/min$0.004/screenshot

Only successful screenshots count toward your quota. Failed requests are not charged. Response headers include X-RateLimit-Remaining.

SDK Quick Start

Drop-in wrapper classes for Node.js and Python. Copy into your project and start capturing.

// Install: npm install node-fetch (or use built-in fetch in Node 18+)

class ScreenshotAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://screenshotapi.site/api/v1/screenshot';
  }

  async capture(url, options = {}) {
    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, ...options }),
    });

    if (!response.ok) {
      const err = await response.json();
      throw new Error(err.error || 'Screenshot failed');
    }
    return response;
  }

  async captureAsBuffer(url, options = {}) {
    const res = await this.capture(url, options);
    return Buffer.from(await res.arrayBuffer());
  }

  async captureAsBase64(url, options = {}) {
    const response = await fetch(this.baseUrl + '?base64=true', {
      method: 'POST',
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, ...options }),
    });
    return response.json();
  }
}

// Usage
const api = new ScreenshotAPI('sk_live_your_key_here');
const buffer = await api.captureAsBuffer('https://github.com', {
  fullPage: true,
  darkMode: true,
  format: 'webp',
});
fs.writeFileSync('screenshot.webp', buffer);

AI Agent Integration

ScreenshotAPI is designed to be discovered and used by AI agents. Use these machine-readable endpoints for automated integration.

OpenAPI 3.1 Spec
/api/openapi.json

Machine-readable API specification. Compatible with Swagger, Postman, and agent tool registries.

AI Plugin Manifest
/.well-known/ai-plugin.json

Standard AI agent plugin manifest. Auto-discovered by LLM tool frameworks and agent platforms.

Error Codes

400
Invalid request parameters or JSON body
401
Missing or invalid API key
403
API key is deactivated
429
Rate limit or quota exceeded
500
Server error during screenshot generation

Smart Screenshots (AI-Driven)

Growth+

Let an AI agent interact with the page before capturing. Click buttons, fill forms, dismiss popups, scroll to content — then screenshot the result.

Endpoint

POST https://screenshotapi.site/api/v1/smart-screenshot

Parameters

ParameterTypeDescription
urlstringTarget URL (required)
taskstringWhat the AI should do before capturing (required). E.g. "Click 'Accept Cookies', then scroll to the pricing section"
maxStepsnumberMax AI actions (1-15, default 10)
formatstringpng, jpeg, or webp
viewportobject{ width, height }
timeoutnumberMax time in ms (5000-120000, default 60000)

Example

curl -X POST https://screenshotapi.site/api/v1/smart-screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "task": "Click Accept Cookies, scroll to pricing"
  }'

Response

{
  "success": true,
  "image": "base64...",
  "steps": [
    { "step": 1, "action": "click", "description": "Clicking Accept Cookies button" },
    { "step": 2, "action": "scroll", "description": "Scrolling to pricing section" },
    { "step": 3, "action": "done", "description": "Task complete" }
  ],
  "credits_used": 10,
  "credits_remaining": 9990
}

Credit cost: Each Smart Screenshot uses 20 credits (Growth) or 40 credits (Scale) from your monthly quota. Available on Growth and Scale plans only.

README Badge

Add this badge to your GitHub repo to show your project uses ScreenshotAPI.

screenshots by ScreenshotAPI
[![ScreenshotAPI](https://img.shields.io/badge/screenshots-ScreenshotAPI-6366f1)](https://screenshotapi.site)

Copy the markdown above and paste it into your README.md file.