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 CodeMeaningDescription
400Bad RequestYour request is malformed.
401UnauthorizedYour API key is wrong or missing.
403ForbiddenYou do not have permission to access this resource.
404Not FoundThe requested resource could not be found.
429Too Many RequestsYou're hitting the API too often. Please slow down.
500Internal Server ErrorWe had a problem with our server. Try again later.

Endpoints

1. Capture Screenshot

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

  • Method: POST
  • URL: "/api/v1/capture"
Headers:
    "Authorization: Bearer YOUR_API_KEY"
    "Content-Type: application/json"

Body Parameters (JSON):

ParameterTypeRequiredDescriptionExample
urlStringYesThe URL of the webpage to capture."https://example.com"
formatStringNoThe desired format of the screenshot. Options: png, jpeg, webp. Defaults to png."jpeg"
widthIntegerNoThe width of the browser viewport in pixels. Defaults to 1920.1280
heightIntegerNoThe height of the browser viewport in pixels. Defaults to 1080.720
fullPageBooleanNoWhether to capture the full scrollable page. Defaults to false.true
  • 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",
        "jobId": "some-unique-job-id",
        "message": "Screenshot request accepted and is being processed.",
        // "screenshotUrl": "https://cdn.screenshotly.app/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/capture/{jobId}"
  • Headers:
    • "Authorization: Bearer YOUR_API_KEY"
  • Path Parameters:
    ParameterTypeDescription
    jobIdStringThe ID of the screenshot job.
  • Success Response (200 OK):
    {
      "jobId": "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://cdn.screenshotly.app/screenshots/some-unique-id.png", // if completed
      "format": "png",
      "error": null // or error message if status is "failed"
    }
    
  • Error Response: See Error Handling.

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")

Webhooks

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}".