API Documentation

Welcome to the ScreenshotAPI documentation. This guide will help you integrate our screenshot service into your application.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer sk_your_api_key

You can also use the X-API-Key header:

X-API-Key: sk_your_api_key

Rate Limits

Rate limits depend on your plan:

Plan	Requests/minute	Screenshots/month
Free	10	100
Starter	30	1,000
Pro	60	5,000
Business	120	25,000

Rate limit information is included in response headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 45
X-Usage-Limit: 1000
X-Usage-Used: 150
X-Usage-Remaining: 850

Screenshot Endpoint

POST /v1/screenshot

Capture a screenshot of any webpage.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The URL to capture
`format`	string	No	Output format: `png`, `jpeg`, `webp` (default: png)
`width`	number	No	Viewport width in pixels (default: 1280, max: 3840)
`height`	number	No	Viewport height in pixels (default: 720, max: 2160)
`fullPage`	boolean	No	Capture full scrollable page (default: false)
`mobile`	boolean	No	Emulate mobile device (default: false)
`delay`	number	No	Wait ms before capture (max: 10000)
`selector`	string	No	CSS selector to capture specific element
`quality`	number	No	JPEG/WebP quality 1-100 (default: 80)
`scale`	number	No	Device scale factor 1-3 (default: 1)
`darkMode`	boolean	No	Prefer dark color scheme (default: false)
`timeout`	number	No	Page load timeout in ms (max: 55000)
`returnType`	string	No	`url`, `base64`, or `binary` (default: url)

Example Request

curl -X POST https://api.screenshotapi.dev/v1/screenshot \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "width": 1280,
    "height": 720,
    "fullPage": true
  }'

Example Response

{
  "success": true,
  "data": {
    "url": "https://screenshots.screenshotapi.dev/abc123.png",
    "width": 1280,
    "height": 2400,
    "format": "png",
    "size": 245678,
    "expiresAt": "2024-01-24T12:00:00.000Z"
  }
}

PDF Endpoint

POST /v1/pdf

Generate a PDF from any webpage.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The URL to convert
`format`	string	No	Page format: `A4`, `Letter`, `Legal` (default: A4)
`landscape`	boolean	No	Landscape orientation (default: false)
`printBackground`	boolean	No	Print background graphics (default: true)
`scale`	number	No	Scale factor 0.1-2 (default: 1)
`margin`	object	No	Page margins: `{ top, right, bottom, left }`

Example Request

curl -X POST https://api.screenshotapi.dev/v1/pdf \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "A4",
    "printBackground": true
  }'

Usage Endpoint

GET /v1/usage

Get your current usage statistics.

Example Response

{
  "success": true,
  "data": {
    "plan": "starter",
    "period": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "usage": {
      "screenshots": 150,
      "limit": 1000,
      "remaining": 850,
      "percentUsed": 15
    },
    "rateLimit": {
      "requestsPerMinute": 30
    }
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Invalid or missing API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests per minute
`USAGE_LIMIT_EXCEEDED`	402	Monthly usage limit exceeded
`INVALID_URL`	400	Invalid URL format
`INVALID_PARAMETERS`	400	Invalid request parameters
`SCREENSHOT_FAILED`	500	Failed to capture screenshot
`TIMEOUT`	504	Request timed out

Code Examples

JavaScript (Node.js)

const response = await fetch('https://api.screenshotapi.dev/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'png',
    fullPage: true
  })
});

const data = await response.json();
if (data.success) {
  console.log('Screenshot URL:', data.data.url);
}

Python

import requests

response = requests.post(
    'https://api.screenshotapi.dev/v1/screenshot',
    headers={
        'Authorization': 'Bearer sk_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://example.com',
        'format': 'png',
        'fullPage': True
    }
)

data = response.json()
if data['success']:
    print('Screenshot URL:', data['data']['url'])

PHP

<?php
$ch = curl_init('https://api.screenshotapi.dev/v1/screenshot');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_your_api_key',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://example.com',
    'format' => 'png',
    'fullPage' => true
]));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if ($data['success']) {
    echo 'Screenshot URL: ' . $data['data']['url'];
}