Node.js SDK

The official Node.js SDK for the Screenshot Scout screenshot API. It is distributed on npm as @screenshotscout/sdk and developed in the screenshotscout-node repository.

Installation

Install the package from npm:

npm install @screenshotscout/sdk

The SDK requires Node.js 22 or newer, and works with both TypeScript and JavaScript. The examples on this page use TypeScript; JavaScript users can use the same API by omitting TypeScript-only syntax.

In a CommonJS project running Node.js 22.12 or newer, load the SDK with require():

const { ScreenshotScoutClient } = require("@screenshotscout/sdk");

Get your API credentials

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page, copy the access key and secret key, and store them in a safe place.

Capture a screenshot

Create a client with your access key and call capture() with the URL of the page you would like to take a screenshot of:

import { writeFile } from "node:fs/promises";
import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient({ accessKey: "YOUR_ACCESS_KEY" });

const response = await client.capture("https://example.com", {
  fullPage: true,
});

await writeFile("screenshot.png", response.bytes);
console.log(response.screenshotUrl);

capture() sends a POST request by default. The responseType capture option selects the response format. When you leave it unset, the call returns a BinaryCaptureResponse: the image data is in bytes, and the exact screenshot URL is in screenshotUrl when available.

Request a JSON result

Set responseType to CaptureResponseType.JSON to receive a JSON object with the screenshot URL instead of the image bytes:

import {
  CaptureResponseType,
  ScreenshotScoutClient,
} from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient({ accessKey: "YOUR_ACCESS_KEY" });

const response = await client.capture("https://example.com", {
  responseType: CaptureResponseType.JSON,
});

console.log(response.result.screenshotUrl);

The parsed JSON body is in result.

Set capture options

The second argument of capture() accepts every option in the screenshot option reference through camelCase properties: full_page becomes fullPage, block_cookie_banners becomes blockCookieBanners, and so on. Options with a fixed set of documented values have exported constants, such as CaptureFormat.WEBP and CaptureWaitUntil.LOAD; raw string values are also accepted.

Build a capture URL

buildCaptureUrl() creates a capture URL without making an API request, for cases where another application or an HTML <img> element loads the screenshot directly:

import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient({ accessKey: "YOUR_ACCESS_KEY" });

const captureUrl = client.buildCaptureUrl("https://example.com", {
  fullPage: true,
  blockAds: true,
});

console.log(captureUrl);

The generated URL contains the access key. When a secret key is configured (see Signed requests), the SDK signs the URL automatically; otherwise it is unsigned. Treat generated URLs as sensitive. Before exposing one to browsers or users, configure a secret key and enable Require signed requests on the API Keys page.

Signed requests

Pass the API key's secret key when creating the client:

import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient({
  accessKey: "YOUR_ACCESS_KEY",
  secretKey: "YOUR_SECRET_KEY",
});

The secret is used locally and is never transmitted. The client signs capture requests and generated capture URLs automatically. See the signed requests guide for details.

Errors

When the API returns a non-2xx response, the SDK throws ScreenshotScoutApiError, with the machine-readable error code in errorCode and the descriptive message in errorMessage. The repository README documents all error classes.

Full reference

This page covers installation and your first captures. For everything else, see:

The repository README: GET requests, timeouts and cancellation, a custom Fetch transport, raw responses, and all error classes.
The standalone examples in the repository.
The screenshot option reference: service behavior and allowed values for every option.

Node.js SDK

On this page