Integration Guides

This section provides step-by-step guides on how to integrate Screenshotly into your existing projects and workflows.

General Integration Principles

Before diving into specific guides, here are some general principles:

  • API Key: Ensure you have your Screenshotly API key, which can be found in your account dashboard.
  • Authentication: All API requests must be authenticated using your API key in the Authorization header. See the API Reference for details.
  • Error Handling: Implement robust error handling in your integration to manage potential API errors. Refer to the Error Handling section in the API reference.

Platform & Language Guides

Choose a guide below based on your technology stack:

1. Node.js / JavaScript

Using the screenshotly-js Client Library

We provide an official JavaScript client library for easy integration with Screenshotly.

Installation
npm install screenshotly-js

Or with yarn:

yarn add screenshotly-js
Basic Example
const { Screenshotly } = require('screenshotly-js');

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

// Capture a screenshot of a URL
async function captureScreenshot() {
  const screenshot = await client.capture({
    url: 'https://example.com',
    width: 1280,
    height: 800,
    fullPage: true,
    delay: 500
  });

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

captureScreenshot();
Batch Screenshots
const { Screenshotly } = require('screenshotly-js');
const client = new Screenshotly('your-api-key-here');

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

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

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

// You can also pass configuration options
const client = new Screenshotly({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.screenshotly.dev',
  timeout: 90000 // 90 seconds timeout for large pages
});

async function captureWithAdvancedOptions() {
  const screenshot = await client.capture({
    url: 'https://example.com',
    format: 'png',
    width: 1920,
    height: 1080,
    fullPage: true,
    deviceScaleFactor: 2, // Retina-quality screenshot
    isMobile: true,
    hasTouch: true,
    waitForSelector: '.content-loaded',
    delay: 1000, // Wait 1 second before capturing
    timeout: 45000 // 45 seconds timeout
  });
  
  console.log('Screenshot URL:', screenshot.data.imageUrl);
}
API Reference
Screenshotly Class

Constructor

// Simple format
new Screenshotly(apiKey)

// Advanced format
new Screenshotly(config)

  • apiKey
    (string): Your Screenshotly API key
  • config.apiKey
    (required): Your Screenshotly API key
  • config.baseUrl
    (optional): Custom API base URL (default: 'https://api.screenshotly.dev')
  • config.timeout
    (optional): Request timeout in milliseconds (default: 60000)

Methods

capture(options): Promise

Captures a screenshot of the specified URL. Options:

  • url
    : URL to capture (required)
  • name
    : Optional name for the screenshot
  • width
    : Width of the viewport in pixels (default: 1920)
  • height
    : Height of the viewport in pixels (default: 1080)
  • fullPage
    : Whether to capture the full page or just the viewport (default: false)
  • format
    : Output format ('png', 'jpeg', 'webp') (default: 'png')
  • deviceScaleFactor
    : Device scale factor (default: 1)
  • isMobile
    : Whether to emulate a mobile device (default: false)
  • hasTouch
    : Whether the device has touch capabilities (default: false)
  • isLandscape
    : Whether to use landscape orientation (default: false)
  • waitForSelector
    : Optional selector to wait for before taking the screenshot
  • delay
    : Delay in milliseconds before capturing the screenshot (default: 0)
  • timeout
    : Timeout in milliseconds (default: 30000)

captureBatch(request): Promise

Captures multiple screenshots in batch. Request:

  • urls
    : Array of URLs to take screenshots of
  • options
    : Screenshot options (applied to all URLs)

getScreenshots(page, limit): Promise

Gets a list of your screenshots.

  • page
    : Page number (default: 1)
  • limit
    : Number of items per page (default: 10)

getScreenshot(id): Promise

Gets a specific screenshot by ID.

deleteScreenshot(id): Promise

Deletes a screenshot by ID.

Using Direct API Calls

// Example: Basic Node.js integration (using axios)
const axios = require('axios');

const SCREENSHOTLY_API_KEY = 'YOUR_API_KEY';
const SCREENSHOTLY_API_URL = 'https://api.screenshotly.dev/api/v1/screenshots'; // Or your API endpoint

async function captureScreenshot(urlToCapture) {
  try {
    const response = await axios.post(SCREENSHOTLY_API_URL, {
      url: urlToCapture,
      // Add other options like format, fullPage, viewport, etc.
    }, {
      headers: {
        'Authorization': `Bearer ${SCREENSHOTLY_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });

    console.log('Screenshot captured successfully:');
    // Depending on your API response, you might get image data directly, a URL, or a job ID
    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error('Error capturing screenshot:', error.response ? error.response.data : error.message);
    throw error;
  }
}

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

2. Python

# Example: Basic Python integration (using requests)
import requests
import json

SCREENSHOTLY_API_KEY = 'YOUR_API_KEY'
SCREENSHOTLY_API_URL = 'https://api.screenshotly.dev/api/v1/screenshots' # Or your API endpoint

def capture_screenshot(url_to_capture):
    headers = {
        'Authorization': f'Bearer {SCREENSHOTLY_API_KEY}',
        'Content-Type': 'application/json'
    }
    payload = {
        'url': url_to_capture,
        # Add other options like format, fullPage, viewport, etc.
    }
    try:
        response = requests.post(SCREENSHOTLY_API_URL, headers=headers, json=payload)
        response.raise_for_status() # Raises an HTTPError for bad responses (4XX or 5XX)
        
        print('Screenshot captured successfully:')
        # Depending on your API response
        print(response.json())
        return response.json()
    except requests.exceptions.HTTPError as http_err:
        print(f'HTTP error occurred: {http_err}')
        print(f'Response content: {response.content}')
        raise
    except Exception as err:
        print(f'Other error occurred: {err}')
        raise

# capture_screenshot('https://example.com')

3. cURL / Command Line

# Example: Basic cURL integration
API_KEY="YOUR_API_KEY"
URL_TO_CAPTURE="https://example.com"

curl -X POST "https://api.screenshotly.dev/api/v1/screenshots" \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "url": "'"$URL_TO_CAPTURE"'",
           "format": "png"
         }' \
     # --output screenshot.png # Uncomment to save if API returns image directly

4. No-Code Platforms

If your no-code platform supports webhooks or HTTP requests, you can integrate Screenshotly using the API endpoints. For example, you can use Webflow's Make an API Call action or Bubble's API Connector to capture screenshots.

If you have a specific integration scenario not covered here, please contact support or check our community forums (if applicable).