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.

Client Libraries

We provide official client libraries to make integration with Screenshotly even easier:

• JavaScript/Node.js:
  Copy

  screenshotly-js

  - Our official JavaScript client for Node.js and browser environments
• Python: Coming soon
• PHP: Coming soon

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 screenshotly-api-key header of your requests.

  screenshotly-api-key: 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:

Endpoints

1. Capture Screenshot

This endpoint allows you to request a screenshot of a given URL.

• Method: POST
• URL: "/api/v1/screenshots"

Headers:
    "screenshotly-api-key: YOUR_API_KEY"
    "Content-Type: application/json"

Body Parameters (JSON):

• Success Response (202 Accepted): Indicates that the screenshot request has been accepted and is being processed. If webhookUrl is not provided, the response will contain the direct URL to the screenshot once ready. If webhookUrl is provided, the response will be minimal, and the result will be sent to the webhook.

    {
      "status": "processing",
      "id": "some-unique-screenshot-id",
      "message": "Screenshot request accepted and is being processed.",
      // "screenshotUrl": "https://api.screenshotly.dev/api/v1/screenshots/some-unique-id.png" // If no webhook
    }
  

• Error Response: See Error Handling.

2. Get Screenshot Status / Details

Retrieve the status or details of a previously submitted screenshot job.

• Method: GET
• URL: "/api/v1/screenshots/{screenshotId}"
• Headers:
  • "screenshotly-api-key: YOUR_API_KEY"
• Path Parameters:

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

• Success Response (200 OK):

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

• Error Response: See Error Handling.

JavaScript Client

Our official JavaScript client library,

screenshotly-js

Installation

npm install screenshotly-js
# or
yarn add screenshotly-js

Usage

const { Screenshotly } = require('screenshotly-js');

// Initialize with your API key
const client = new Screenshotly('your-api-key-here');

// Or with advanced options
const clientWithOptions = new Screenshotly({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.screenshotly.dev', // optional custom API URL
  timeout: 60000 // optional timeout in milliseconds
});

API Methods

capture(options)

Captures a screenshot of a specified URL.

const screenshot = await client.capture({
  url: 'https://example.com',
  width: 1280,
  height: 800,
  fullPage: true,
  format: 'png',
  delay: 500
});

if (screenshot.success) {
  console.log('Screenshot URL:', screenshot.data.imageUrl);
  console.log('Remaining credits:', screenshot.remainingCredits);
} else {
  console.error('Error:', screenshot.error);
}

Parameters:

captureBatch(request)

Captures multiple screenshots in batch.

const result = await client.captureBatch({
  urls: [
    'https://example.com',
    'https://google.com',
    'https://github.com'
  ],
  options: {
    format: 'png',
    width: 1280,
    height: 800,
    fullPage: true
  }
});

if (result.success) {
  console.log('Screenshots:', result.data);
  console.log('Remaining credits:', result.remainingCredits);
} else {
  console.error('Error:', result.error);
}

Parameters:

getScreenshots(page, limit)

Gets a list of your screenshots.

const screenshots = await client.getScreenshots(1, 10);
console.log('Screenshots:', screenshots.data);

Parameters:

getScreenshot(id)

Gets a specific screenshot by ID.

const screenshot = await client.getScreenshot('screenshot-id');
console.log('Screenshot:', screenshot.data);

deleteScreenshot(id)

Deletes a screenshot by ID.

const result = await client.deleteScreenshot('screenshot-id');
console.log('Deleted:', result.success);

For more detailed examples and advanced usage, see our Integration Guides.

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.dev/api/v1/screenshots';

async function captureScreenshot(urlToCapture) {
  try {
    const response = await axios.post(
      SCREENSHOTLY_API_ENDPOINT,
      {
        url: urlToCapture,
        format: 'jpeg',
        fullPage: true,
      },
      {
        headers: {
          'screenshotly-api-key': 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.dev/api/v1/screenshots"

def capture_screenshot(url_to_capture):
    headers = {
        "screenshotly-api-key": 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")

Changelog

Stay updated with the latest changes to our API.

• v1.0.0 (2025-05-14)
  • Initial API release.
  • Endpoints: "/screenshots", "/screenshots/{screenshotId}".