Start here

Client libraries

Official libraries for Node.js, Python, Java, .NET, Go, PHP and Ruby. Each one covers both APIs, takes care of retries, timeouts and webhook signatures, and is installed from your language's usual package registry.

Languages and packages

Every library is open source under the MIT licence, lives in its own repository, and follows the same specification, so a capture written in one language reads the same in another. You do not need a library to use the APIs - they are plain HTTPS and JSON - but a library saves you writing the retry, timeout and signature code yourself.

ValueMeaning
Node.js@websitescreenshotworld/sdk on npm, version 0.1.1. Node.js 22 or later (TypeScript types included). Source on GitHub.
Pythonwebsitescreenshotworld on PyPI, version 0.1.0. Python 3.10 or later, with an asyncio client too. Source on GitHub.
Javacom.websitescreenshotworld:websitescreenshotworld-java on Maven Central, version 0.1.0. Java 11 or later. Source on GitHub.
C# (.NET)WebsiteScreenshotWorld on NuGet, version 0.1.0. .NET 8 or later, or any .NET Standard 2.0 runtime; dependency injection support in a second package. Source on GitHub.
Gogithub.com/websitescreenshotworld/websitescreenshotworld-go on Go modules, version 0.1.0. Go 1.22 or later, no dependencies outside the standard library. Source on GitHub.
PHPwebsitescreenshotworld/websitescreenshotworld-php on Packagist, version 0.1.0. PHP 8.2 or later, with any PSR-18 HTTP client such as Guzzle. Source on GitHub.
Rubywebsitescreenshotworld on RubyGems, version 0.1.3. Ruby 3.2 or later, no runtime dependencies. Source on GitHub.

Install

npm install @websitescreenshotworld/sdk

Java with Maven instead of Gradle: add the dependency com.websitescreenshotworld / websitescreenshotworld-java to your pom.xml. For .NET applications that use dependency injection, WebsiteScreenshotWorld.Extensions.DependencyInjection registers the client with services.AddWebsiteScreenshotWorld().

Your first capture

Create an Instant Snap API key under Developer Tools › API Keys in the app, and put it in the environment. Every library reads its keys from these two variables when you do not pass them in, and you only need the key of the API you call.

export WSW_INSTANT_SNAP_API_KEY="wsw_api_..."      # Instant Snap API
export WSW_AUTO_SCHEDULE_API_KEY="wsw_autoapi_..."  # Auto Schedule API

Then capture a page. The answer is the capture itself - its id, size, checksum and a download link that stays valid for 60 minutes.

import { WebsiteScreenshotWorld } from "@websitescreenshotworld/sdk";

// Reads WSW_INSTANT_SNAP_API_KEY from the environment.
const client = new WebsiteScreenshotWorld();

const capture = await client.instantSnap.capture({
  url: "https://example.com",
  format: "webp",
  viewport: { width: 1440, height: 900 },
});

console.log(capture.downloadUrl); // valid for 60 minutes

Every option of the API is available, named in your language's own style - full-page capture, PDFs, the page source, devices, locations, cookies, watermarks and delivery to your own S3 bucket. An option you leave out is not sent, so the API applies its default; the request parameters page lists them all. Each library can also save the file straight to disk, submit a capture to run in the background and wait for it, or read a stored capture back by its id.

Trigger a schedule

With an Auto Schedule API key, the same client starts a capture of a web page you already scheduled in the app. Calling it again while that capture is still pending starts nothing new. The capture's result arrives by webhook.

const result = await client.autoSchedule.triggerNow("7d4e2b1a-6c5f-4a3e-9d8c-2b1a0f9e8d7c");

if (result.status === "already_pending") {
  console.log("A capture of this page was already on its way.");
}

What the libraries do for you

  • Retries that cannot double-charge. A request that failed on the network or met a busy service is retried up to twice, with a short back-off or the wait the API asked for. Every capture carries an idempotency key, reused on its retries, so a retried capture is never run twice.
  • One timeout for the whole call. 180 seconds for a capture and 30 for anything else, covering every attempt and the waits between them.
  • Typed errors. Each refusal raises an error of its kind - authentication, invalid request, plan limit, rate limit, capture failed and so on - carrying the API's error_code, so you can handle the cases you care about.
  • Your key stays where you sent it. No library follows a redirect with your API key on the request.
  • Forward-compatible answers. A field or value the API adds later is passed through, not treated as an error, so an older library keeps working.

Verifying webhooks

Each library includes Webhook.verify (named in your language's style). Give it the raw request body, the X-WSW-Signature header and your endpoint's secret; it checks the signature and the timestamp, and returns the event as a typed object - a finished or failed capture, a changed page, a completed delivery, a paused schedule or a finished sitemap run. The webhooks guide explains the events, and each library's README shows how to read the raw body in its common web frameworks.

Verify the raw body

A framework that parses the JSON and serialises it again changes the bytes, and the signature no longer matches. Read the body as received and pass that to verify.

Source, versions and issues

The libraries follow semantic versioning, and each repository has a changelog. All seven are tested against the same shared specification and conformance cases. Found a bug or missing an option? Open an issue in the library's repository, or email support.

Did this page answer your question?

Tell us what is missing