API Documentation

Welcome to the WebsiteScreenshot API documentation. Our API allows you to capture high-quality screenshots and videos of any website programmatically.

Base URL

Http

https://websitescreenshot.online/api/v1

Authentication

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

Http

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Sign up for an account at websitescreenshot.online
Navigate to your Dashboard
Create a new API key with your desired settings
Copy both the API key and Secret key (if signature validation is enabled)

Rate Limits

Screenshot API: 10 requests per minute
Video API: 5 requests per minute
General API: 100 requests per 15 minutes

Rate limit headers are included in all responses:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when the rate limit resets

Screenshot API

POST /api/v1/screenshot

Capture a screenshot of any website.

Request Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The URL to capture (must include http:// or https://)
`resolution`	object	No	Viewport dimensions object with `width` and `height` properties
`resolution.width`	integer	No	Viewport width in pixels
`resolution.height`	integer	No	Viewport height in pixels
`fullSize`	boolean	No	Capture full page height (default: false), if true, the height in resolution will be ignored
`format`	string	No	Output format: `png`, `jpeg`, `pdf` (default: `png`)
`blockCookiesGdpr`	boolean	No	Block cookie consent popups (default: true)
`blockAds`	boolean	No	Block advertisements (default: true)
`delay`	integer	No	Wait time in seconds before capture (default: 1, max: 10)

Example Requests

JavaScript (Node.js)

Javascript

const axios = require('axios');

async function captureScreenshot() {
  try {
    const response = await axios.post('https://websitescreenshot.online/api/v1/screenshot', {
      url: 'https://example.com',
      resolution: {
        width: 1920,
        height: 1080
      },
      format: 'png',
      fullSize: true,
      blockCookiesGdpr: true,
      blockAds: true,
      delay: 3
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Screenshot URL:', response.data.url);
    console.log('File size:', response.data.size);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

captureScreenshot();

JavaScript (Fetch)

Javascript

async function captureScreenshot() {
  try {
    const response = await fetch('https://websitescreenshot.online/api/v1/screenshot', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        url: 'https://example.com',
        resolution: {
          width: 1920,
          height: 1080
        },
        format: 'png',
        fullSize: true,
        blockCookiesGdpr: true,
        blockAds: true,
        delay: 2
      })
    });
    
    const data = await response.json();
    
    if (response.ok) {
      console.log('Screenshot URL:', data.url);
      console.log('File size:', data.size);
    } else {
      console.error('Error:', data.error);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
}

captureScreenshot();

Python

import requests
import json

def capture_screenshot():
    url = "https://websitescreenshot.online/api/v1/screenshot"
    
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    data = {
        "url": "https://example.com",
        "resolution": {
            "width": 1920,
            "height": 1080
        },
        "format": "png",
        "fullSize": True,
        "blockCookiesGdpr": True,
        "blockAds": True,
        "delay": 2
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        
        result = response.json()
        print(f"Screenshot URL: {result['url']}")
        print(f"File size: {result['size']}")
        
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        if hasattr(e.response, 'json'):
            print(f"Details: {e.response.json()}")

capture_screenshot()

PHP

Php

<?php

function captureScreenshot() {
    $url = 'https://websitescreenshot.online/api/v1/screenshot';
    
    $data = [
        'url' => 'https://example.com',
        'resolution' => [
            'width' => 1920,
            'height' => 1080
        ],
        'format' => 'png',
        'fullSize' => true,
        'blockCookiesGdpr' => true,
        'blockAds' => true,
        'delay' => 3
    ];
    
    $options = [
        'http' => [
            'header' => [
                'Authorization: Bearer YOUR_API_KEY',
                'Content-Type: application/json'
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        echo "Error occurred\n";
        return;
    }
    
    $response = json_decode($result, true);
    
    if (isset($response['url'])) {
        echo "Screenshot URL: " . $response['url'] . "\n";
        echo "File size: " . $response['size'] . "\n";
    } else {
        echo "Error: " . ($response['error'] ?? 'Unknown error') . "\n";
    }
}

captureScreenshot();
?>

cURL

Bash

curl -X POST https://websitescreenshot.online/api/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "resolution": {"width": 1920, "height": 1080},
    "format": "png",
    "fullSize": true,
    "blockCookiesGdpr": true,
    "blockAds": true,
    "delay": 2
  }'

Response

Json

{
  "success": true,
  "imageUrl": "https://websitescreenshot.online/screenshots/example-com-2024-01-15-123456.png",
  "filename": "example-com-2024-01-15-123456.png"
}

Video Recording API

POST /api/v1/video

Record a video of website interactions.

Request Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The URL to record
`resolution`	object	No	Viewport dimensions object with `width` and `height` properties
`resolution.width`	integer	No	Viewport width in pixels
`resolution.height`	integer	No	Viewport height in pixels
`format`	string	No	Output format: `webm`, `mp4` (default: `webm`)
`scrollDistance`	integer	No	Distance to scroll in pixels (default: 500, min: 100, max: 1000)
`scrollDelay`	integer	No	Delay between scrolls in milliseconds (default: 1000, min: 200, max: 5000)
`blockCookiesGdpr`	boolean	No	Block cookie consent popups (default: true)
`blockAds`	boolean	No	Block advertisements (default: true)
`delay`	integer	No	Wait time in seconds before recording (default: 1, max: 10)

Example Request

Javascript

const response = await fetch('https://websitescreenshot.online/api/v1/video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    resolution: {
      width: 1920,
      height: 1080
    },
    format: 'webm',
    scrollDistance: 500,
    scrollDelay: 1000,
    blockCookiesGdpr: true,
    blockAds: true,
    delay: 1
  })
});

const data = await response.json();
console.log('Video URL:', data.videoUrl);

Response

Json

{
  "success": true,
  "videoUrl": "https://websitescreenshot.online/videos/example-com-2024-01-15-123456.webm",
  "filename": "example-com-2024-01-15-123456.webm"
}

Request Signing (Enhanced Security)

For enhanced security, you can enable request signing for your API keys. This protects against replay attacks and ensures request integrity.

Enabling Request Signing

When creating an API key, check "Require Request Signatures"
Save both the API key and the Secret key
Include signature headers in your requests

Required Headers

X-Timestamp: Current Unix timestamp in milliseconds
X-Nonce: Random string (16+ characters recommended)
X-Signature: HMAC-SHA256 signature

Signature Generation

The signature is generated using HMAC-SHA256 with the following payload:

Text

METHOD|URL|TIMESTAMP|NONCE

JavaScript Example

Javascript

const crypto = require('crypto');

function generateSignature(method, url, timestamp, nonce, secretKey) {
  const payload = `${method}|${url}|${timestamp}|${nonce}`;
  return crypto.createHmac('sha256', secretKey).update(payload).digest('hex');
}

async function signedRequest() {
  const method = 'POST';
  const url = 'https://websitescreenshot.online/api/v1/screenshot';
  const timestamp = Date.now().toString();
  const nonce = crypto.randomBytes(16).toString('hex');
  const signature = generateSignature(method, url, timestamp, nonce, 'YOUR_SECRET_KEY');
  
  const response = await fetch(url, {
    method: method,
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Signature': signature
    },
    body: JSON.stringify({
      url: 'https://example.com'
    })
  });
  
  return response.json();
}

Python Example

Python

import hmac
import hashlib
import time
import secrets

def generate_signature(method, url, timestamp, nonce, secret_key):
    payload = f"{method}|{url}|{timestamp}|{nonce}"
    return hmac.new(
        secret_key.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

def signed_request():
    method = "POST"
    url = "https://websitescreenshot.online/api/v1/screenshot"
    timestamp = str(int(time.time() * 1000))
    nonce = secrets.token_hex(16)
    signature = generate_signature(method, url, timestamp, nonce, "YOUR_SECRET_KEY")
    
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature
    }
    
    # Make your request with these headers

Error Responses

All errors follow a consistent format:

Json

{
  "code": "ERROR_CODE",
  "error": "Error message"
}

Common Error Codes

Code	Status	Description
`HTTPS_REQUIRED`	400	HTTPS required. API requests must use HTTPS in production.
`INVALID_URL`	400	The provided URL is invalid or unreachable
`SIGNATURE_INVALID`	400	Request signature validation failed
`TIMEOUT`	400	Request timed out
`DNS_RESOLUTION`	400	DNS resolution failed
`CONNECTION_REFUSED`	400	Connection refused
`SSL_CERTIFICATE`	400	SSL certificate error
`PAGE_NOT_FOUND`	400	Page not found
`INVALID_PARAMETERS`	400	One or more parameters are invalid
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	IP address not in whitelist
`RATE_LIMITED`	429	Rate limit exceeded
`USAGE_LIMIT_EXCEEDED`	429	Usage limit exceeded
`INTERNAL_ERROR`	500	Internal server error

Best Practices

1. Handle Rate Limits

Always check rate limit headers and implement exponential backoff:

Javascript

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = Math.max(1000, (resetTime * 1000) - Date.now());
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

2. Validate URLs

Always validate URLs before making requests:

Javascript

function isValidUrl(string) {
  try {
    const url = new URL(string);
    return url.protocol === 'http:' || url.protocol === 'https:';
  } catch (_) {
    return false;
  }
}

3. Use Appropriate Timeouts

Set reasonable timeouts for your requests:

Javascript

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 seconds

try {
  const response = await fetch(url, {
    ...options,
    signal: controller.signal
  });
} finally {
  clearTimeout(timeoutId);
}

4. Store Files Securely

If downloading files, ensure secure storage:

Javascript

async function downloadAndStore(screenshotUrl) {
  const response = await fetch(screenshotUrl);
  const buffer = await response.arrayBuffer();
  
  // Store securely with proper access controls
  // Consider using cloud storage with signed URLs
}

SDKs and Libraries

We're working on official SDKs for popular programming languages. In the meantime, you can use the HTTP examples above or create wrapper functions for your preferred language.

Support

Documentation: websitescreenshot.online/docs
Dashboard: websitescreenshot.online/dashboard
Contact: Reach out through Email for technical support: [email protected]