API Documentation

Overview

The BrowserShots API allows you to programmatically capture screenshots of any website. Perfect for:

  • Automated website monitoring
  • Thumbnail generation for link previews
  • Visual regression testing
  • Content archiving
API Access: Available for Super User plan subscribers only.

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header:

X-API-Key: bshots_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can generate API keys in your API Keys page.

IP Whitelist

For additional security, you can restrict API key access to specific IP addresses or CIDR ranges. Configure this in your API Keys settings.

Security: Keep your API keys secret. Never expose them in client-side code or public repositories. Use IP whitelisting for production environments.
Email Verification: Your email must be verified before using the API. Unverified accounts will receive a 403 error.

Base URL

All API endpoints use the following base URL:

https://www.browsershots.at/api/v1

Endpoints

POST /screenshot

Create a new screenshot job.

Request Body
Parameter Type Required Description
url string Yes The URL to screenshot (must include http:// or https://)
devices array No Device types: desktop, tablet, mobile, all. Default: ["desktop"]
callback_url string No Webhook URL to receive notification when screenshot is ready
full_page boolean No Capture full page height (scrolling screenshot). Default: false
googlebot boolean No Use Googlebot user agent (bypasses cookie consent popups, sees page as Google crawler). Default: false
Example Request
curl -X POST https://www.browsershots.at/api/v1/screenshot \
  -H "X-API-Key: bshots_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "devices": ["desktop"],
    "full_page": true,
    "googlebot": true
  }'
Example Response
{
  "job_id": "a1b2c3d4e5f6789012345678",
  "status": "pending",
  "devices": ["desktop"],
  "full_page": true,
  "googlebot": true,
  "estimated_time_seconds": 15,
  "status_url": "https://www.browsershots.at/api/v1/screenshot/a1b2c3d4e5f6789012345678"
}
GET /screenshot/{job_id}

Get the status and result of a screenshot job.

Path Parameters
Parameter Type Description
job_id string The job ID returned from the create endpoint
Example Request
curl https://www.browsershots.at/api/v1/screenshot/72 \
  -H "X-API-Key: bshots_your_api_key"
Example Response (Pending)
{
  "job_id": "72",
  "status": "pending",
  "progress": 0,
  "url": "https://example.com",
  "preset": "desktop",
  "full_page": true,
  "googlebot": true,
  "created_at": "2024-01-15 10:30:00"
}
Example Response (Completed)
{
  "job_id": "72",
  "status": "completed",
  "progress": 100,
  "url": "https://example.com",
  "preset": "desktop",
  "full_page": true,
  "googlebot": true,
  "created_at": "2024-01-15 10:30:00",
  "screenshot_url": "https://www.browsershots.at/screenshots/72_desktop.png",
  "completed_at": "2024-01-15 10:30:15"
}
Example Response (Failed)
{
  "job_id": "72",
  "status": "failed",
  "progress": 0,
  "url": "https://example.com",
  "preset": "desktop",
  "full_page": false,
  "googlebot": false,
  "created_at": "2024-01-15 10:30:00",
  "error": "Connection timeout"
}
Response Fields
Field Type Description
job_id string Unique job identifier
status string pending, processing, completed, or failed
progress integer Progress percentage (0-100)
url string The URL being captured
preset string Device preset: desktop, tablet_landscape, or mobile
full_page boolean Whether full page capture is enabled
googlebot boolean Whether Googlebot user agent is used
created_at string Job creation timestamp
screenshot_url string URL of the screenshot image (only when completed)
completed_at string Completion timestamp (only when completed)
error string Error message (only when failed)
has_page_source boolean Whether page source HTML is available (only when completed)
page_source string HTML source code (only when include_source=1 query param is set)
Page Source: To include the full HTML source in the response, add ?include_source=1 to the GET request. This can significantly increase response size.
Job Status Values
Status Description
pending Job is queued and waiting to be processed
processing Screenshot is being captured
completed Screenshot is ready - check screenshot_url
failed An error occurred - check error field
GET /usage

Get your current API usage statistics.

Example Request
curl https://www.browsershots.at/api/v1/usage \
  -H "X-API-Key: bshots_your_api_key"
Example Response
{
  "calls_today": 42,
  "calls_this_month": 1250,
  "daily_limit": 1000,
  "monthly_limit": 30000,
  "reset_at": "2024-01-16T00:00:00Z"
}

Rate Limits

Plan Daily Limit Rate
Super User 1,000 screenshots/day 10 requests/second

Rate limit headers are included in every response:

  • X-RateLimit-Limit - Maximum requests per day
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Unix timestamp when limit resets

Error Handling

The API uses standard HTTP status codes and returns errors in JSON format:

Rate Limit Error (429)
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily API limit (1000 requests/day)",
  "retry_after": 3600
}
IP Not Whitelisted Error (403)
{
  "error": "IP not allowed",
  "message": "Your IP address (192.168.1.1) is not in the whitelist for this API key"
}
Email Not Verified Error (403)
{
  "error": "Email not verified",
  "message": "Please verify your email address before using the API"
}
HTTP Status Codes
Code Description
200 Success
201 Created (screenshot job queued)
400 Bad Request (invalid parameters)
401 Unauthorized (invalid or missing API key)
403 Forbidden (email not verified, IP not whitelisted, or access denied)
404 Not Found (job doesn't exist)
429 Too Many Requests (rate limit exceeded)
500 Internal Server Error

Code Examples

PHP
<?php
$apiKey = 'bshots_your_api_key';
$url = 'https://www.browsershots.at/api/v1/screenshot';

$data = [
    'url' => 'https://example.com',
    'devices' => ['desktop'],
    'full_page' => true,
    'googlebot' => true  // Bypass cookie popups
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

echo "Job ID: " . $result['job_id'];
Python
import requests

api_key = 'bshots_your_api_key'
url = 'https://www.browsershots.at/api/v1/screenshot'

response = requests.post(url,
    json={
        'url': 'https://example.com',
        'devices': ['desktop'],
        'full_page': True,
        'googlebot': True  # Bypass cookie popups
    },
    headers={
        'X-API-Key': api_key
    }
)

result = response.json()
print(f"Job ID: {result['job_id']}")
JavaScript (Node.js)
const response = await fetch('https://www.browsershots.at/api/v1/screenshot', {
    method: 'POST',
    headers: {
        'X-API-Key': 'bshots_your_api_key',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        url: 'https://example.com',
        devices: ['desktop'],
        full_page: true,
        googlebot: true  // Bypass cookie popups
    })
});

const result = await response.json();
console.log('Job ID:', result.job_id);

Ready to get started?

Upgrade to Super User to access the API.

View Pricing