API Reference

Welcome to the Screenshotly API reference. This document provides all the information you need to interact with the Screenshotly API programmatically.

Introduction

The Screenshotly API is a powerful and flexible tool for capturing high-quality screenshots of web pages. Integrate it into your application to automate the process of generating visual content.

Authentication

All API requests must be authenticated. Screenshotly uses API Keys to allow access to the API.

API Key: You can obtain your API key from your account dashboard.
Header: Include your API key in the Authorization header of your requests, prefixed with Bearer.
```
Authorization: Bearer YOUR_API_KEY
```

Rate Limiting

Our API has a rate limit of X requests per minute per API key. If you exceed this limit, you will receive a "429 Too Many Requests" HTTP status code.

Error Handling

The Screenshotly API uses standard HTTP status codes to indicate the success or failure of an API request.

2xx status codes indicate success.
4xx status codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
5xx status codes indicate an error with Screenshotly's servers (these are rare).

Common error codes include:

Status Code	Meaning	Description
400	Bad Request	Your request is malformed.
401	Unauthorized	Your API key is wrong or missing.
403	Forbidden	You do not have permission to access this resource.
404	Not Found	The requested resource could not be found.
429	Too Many Requests	You're hitting the API too often. Please slow down.
500	Internal Server Error	We had a problem with our server. Try again later.

Parameter	Type	Required	Description	Example
url	String	Yes	The URL of the webpage to capture.	"https://example.com"
format	String	No	The desired format of the screenshot. Options: png, jpeg, webp. Defaults to png.	"jpeg"
width	Integer	No	The width of the browser viewport in pixels. Defaults to 1920.	1280
height	Integer	No	The height of the browser viewport in pixels. Defaults to 1080.	720
fullPage	Boolean	No	Whether to capture the full scrollable page. Defaults to false.	true

Parameter	Type	Description
jobId	String	The ID of the screenshot job.

Code Examples

Here are some examples of how to use the Screenshotly API in different programming languages.

JavaScript (Node.js - axios)

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const SCREENSHOTLY_API_ENDPOINT = 'https://api.screenshotly.app/v1/capture';

async function captureScreenshot(urlToCapture) {
  try {
    const response = await axios.post(
      SCREENSHOTLY_API_ENDPOINT,
      {
        url: urlToCapture,
        format: 'jpeg',
        fullPage: true,
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
      }
    );
    console.log('API Response:', response.data);
    // If not using webhooks, response.data.screenshotUrl will contain the image URL
  } catch (error) {
    console.error('Error capturing screenshot:', error.response ? error.response.data : error.message);
  }
}

captureScreenshot('https://example.com');

Python (using requests library)

import requests
import json

API_KEY = "YOUR_API_KEY"
SCREENSHOTLY_API_ENDPOINT = "https://api.screenshotly.app/v1/capture"

def capture_screenshot(url_to_capture):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "url": url_to_capture,
        "format": "png",
        "width": 1920,
        "height": 1080,
    }
    try:
        response = requests.post(SCREENSHOTLY_API_ENDPOINT, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # Raises an HTTPError for bad responses (4XX or 5XX)
        print("API Response:", response.json())
        # If not using webhooks, response.json().get("screenshotUrl") will contain the image URL
    except requests.exceptions.HTTPError as errh:
        print(f"Http Error: {errh} - {errh.response.text}")
    except requests.exceptions.ConnectionError as errc:
        print(f"Error Connecting: {errc}")
    except requests.exceptions.Timeout as errt:
        print(f"Timeout Error: {errt}")
    except requests.exceptions.RequestException as err:
        print(f"Oops: Something Else: {err}")

capture_screenshot("https://example.com")

If you provide a webhookUrl when requesting a screenshot, Screenshotly will send a POST request to your specified URL once the screenshot processing is complete (either successfully or with an error).

Method: POST
Content-Type: application/json

Payload: The payload will be similar to the response from the "Get Screenshot Status" endpoint.

{
  "jobId": "some-unique-job-id",
  "status": "completed", // or "failed"
  "url": "https://example.com",
  "requestedAt": "2025-05-14T10:00:00Z",
  "completedAt": "2025-05-14T10:00:05Z", // if completed
  "screenshotUrl": "https://cdn.screenshotly.app/screenshots/some-unique-id.png", // if completed
  "format": "png",
  "error": null // or error message if status is "failed"
}

Security: It's recommended to verify webhook requests, for example, by checking a signature if Screenshotly provides one, or by using a hard-to-guess webhook URL.

Changelog

Stay updated with the latest changes to our API.

v1.0.0 (2025-05-14)
- Initial API release.
- Endpoints: "/capture", "/capture/{jobId}".

API Reference

Introduction

Authentication

Rate Limiting

Error Handling

Endpoints

1. Capture Screenshot

2. Get Screenshot Status / Details

Code Examples

JavaScript (Node.js - axios)

Python (using requests library)

Webhooks

Changelog