Getting Started

Welcome to the ScreenshotAPI documentation. This guide will walk you through creating your account, generating an API key, and capturing your first website screenshot in under 5 minutes.

Base URL & Versioning

All API requests use the following base URL:

https://screenshotrun.com/api/v1/

The API is versioned via the URL path (/v1/). When we introduce breaking changes, they will be released under a new version (e.g., /v2/). The current version (v1) will remain supported and functional. Non-breaking additions (new fields, new optional parameters) may be added to v1 without a version bump.

CORS

The API supports Cross-Origin Resource Sharing (CORS) with Access-Control-Allow-Origin: *, allowing requests from any domain. This means you can call the API directly from browser-based JavaScript applications.

Important: If you use the API from client-side code, your API key will be visible to users. Use domain restrictions on your API key to prevent unauthorized usage from other domains.

1. Create an Account

Sign up for a free account at our registration page. No credit card required — the free plan includes up to 300 screenshots per month.

2. Generate an API Key

After signing in, navigate to Dashboard → API Keys and click Create New Key. Give your key a descriptive name (e.g. "Production" or "Development").

Your API key will look like this:

sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ab

Important: Copy your key immediately — for security reasons, it will only be shown once. Store it in a safe place such as an environment variable or a secrets manager.

3. Make Your First Request

Use the following request to capture a screenshot. Replace YOUR_API_KEY with the key you generated in Step 2.

cURL

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

PHP

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://screenshotrun.com/api/v1/screenshots', [
        'url' => 'https://example.com',
    ]);

$screenshot = $response->json('data');
echo $screenshot['id']; // Screenshot ID

Python

import requests

response = requests.post(
    "https://screenshotrun.com/api/v1/screenshots",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://example.com"}
)

screenshot = response.json()["data"]
print(screenshot["id"])  # Screenshot ID

JavaScript (Node.js)

const response = await fetch("https://screenshotrun.com/api/v1/screenshots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

const { data } = await response.json();
console.log(data.id); // Screenshot ID

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://screenshotrun.com/api/v1/screenshots")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = { url: "https://example.com" }.to_json

response = http.request(request)
screenshot = JSON.parse(response.body)["data"]
puts screenshot["id"] # Screenshot ID

Go

payload := strings.NewReader(`{"url": "https://example.com"}`)

req, _ := http.NewRequest("POST", "https://screenshotrun.com/api/v1/screenshots", payload)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"].(map[string]interface{})["id"])

4. Check the Response

A successful request returns a 202 Accepted response. The screenshot is queued for processing:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "url": "https://example.com",
    "options": {
      "width": 1280,
      "height": 800,
      "format": "png",
      "quality": 80,
      "full_page": false,
      "device": "desktop",
      "block_ads": false,
      "block_cookies": true,
      "dark_mode": false,
      "delay": 0,
      "timeout": 30,
      "retina": false
    },
    "estimated_time": 5,
    "created_at": "2026-03-09T10:30:00.000000Z",
    "links": {
      "self": "https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

5. Retrieve the Screenshot

Poll the screenshot status by its id, or use webhooks for real-time notifications. Once the status changes to completed, you can download the image:

# Check status
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000

# Download the image
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000/image \
  -o screenshot.png

6. Understanding Screenshot Statuses

Status	Description
`pending`	Screenshot is queued and will be processed shortly
`processing`	Screenshot is being captured right now
`completed`	Screenshot is ready — image can be downloaded
`failed`	Capture failed — check the `error` field for details

Next Steps

Authentication — Learn about API key security and best practices
Screenshots — Explore all available parameters and endpoints
Webhooks — Set up real-time notifications instead of polling
Account & Usage — Monitor your API usage and limits
SDKs & Libraries — Integration examples for popular languages
Error Codes — Handle errors and rate limits gracefully