Webshot SDKs for JavaScript, Python, and PHP — Now on GitHub

Three official Webshot SDKs just landed on GitHub: JavaScript/TypeScript, Python, and PHP. MIT-licensed, idiomatic to each language, and a three-line quickstart in all of them. Repo: github.com/tuxxin/webshot.site-sdk.

Until today, calling the Webshot API meant either pasting a curl command from the docs page or rolling your own thin wrapper. That worked, but it left every Webshot user re-implementing the same five things: timeout handling, rate-limit detection, retry-after parsing, error class hierarchies, and graceful fallback when the page can’t be captured. We’re consolidating all of that into three official libraries so you can stop reinventing them.

What ships in v1.0.0

Each SDK exposes the exact same surface — a single WebshotClient class with two methods (capture and throttleStatus) and a typed three-tier exception hierarchy. Pick whichever language fits your stack:

JavaScript / TypeScript — npm install @tuxxin/webshot

import { WebshotClient } from '@tuxxin/webshot';
import { writeFile } from 'node:fs/promises';

const client = new WebshotClient();
const shot   = await client.capture({ url: 'https://example.com', format: 'png' });
await writeFile('example.png', shot.bytes);

Works in Node 18+ (uses native fetch) and modern browsers. Ships ESM and CJS bundles plus full TypeScript types. JS package on GitHub.

Python — pip install webshot

from webshot import WebshotClient

with WebshotClient() as client:
    shot = client.capture("https://example.com", format="png")
    shot.write("example.png")

Both WebshotClient (sync) and AsyncWebshotClient (async, httpx-based) ship in the same package. Compatible with Python 3.9+. Single dependency: httpx. Tests use httpx.MockTransport for full unit coverage with no live HTTP. Python package on GitHub.

PHP — composer require tuxxin/webshot

use Tuxxin\Webshot\Client;

$client = new Client();
$shot   = $client->capture('https://example.com', format: 'png');
$shot->write('example.png');

Compatible with PHP 8.1+. Uses the cURL extension directly, no Guzzle dependency. The executeHttp() method is protected, so subclassing to plug in Guzzle or Symfony HttpClient is a one-method override. PHP package on GitHub.

Why typed errors matter (and what we shipped)

Every SDK throws three exception classes in a clean hierarchy:

• WebshotError — the parent. Catch this for “anything went wrong.”
• WebshotApiError — the API returned a 4xx/5xx other than 429. Has status and docsUrl properties.
• WebshotThrottledError — 429 specifically. Has retryAfter, resetAt, limit, available, and contact (defaults to [email protected]).

That last one is the one most apps want. When a user hits the rate limit, your code can show them an actually helpful message:

try {
  const shot = await client.capture({ url });
} catch (err) {
  if (err instanceof WebshotThrottledError) {
    console.log(`Rate limit hit — retry in ${err.retryAfter}s.`);
    console.log(`Need higher limits? Email ${err.contact}`);
  }
}

The same fields are available in Python (e.retry_after, e.contact) and PHP ($e->getRetryAfter(), $e->getContact()) — the API itself emits them in the JSON 429 response, so the SDKs are wrapping fields that already exist rather than inventing client-side state.

What stays the same

The SDKs are thin wrappers around the existing public API. Same engine, same five-captures-per-fifteen-minutes rate limit, same headless Chrome rendering. If you’ve been using curl against /api/capture, the SDK is a drop-in upgrade with type safety and structured error handling — not a different service.

The free public API will always be free. The SDKs are MIT-licensed; use them in personal projects, commercial products, or anything in between.

What about other languages?

The bare API works from any language with an HTTP client. The developers page has working code samples for cURL, Python, Node.js, PHP, and Go. We picked JavaScript, Python, and PHP for the first SDK round because that’s where the inbound traffic lives — if Go, Ruby, Rust, or .NET lights up enough to justify it, we’ll add them next.

If you’d like to contribute one, the existing three are short (~200 lines of client code each) and follow the same contract; a port is mostly translation work. Open an issue on the repo to coordinate.

Higher rate limits

The free tier is 5 captures per 15 minutes per IP, which is right for ad-hoc work and small CI pipelines. If you’re running visual regression on a serious test suite, monitoring competitor pricing daily, or building Webshot into a product, email [email protected] — we usually reply same-day with options.

Get started

• 📦 Repo: github.com/tuxxin/webshot.site-sdk
• 📚 API docs: webshot.site/developers
• 🚀 Use-case landing pages: webshot.site/use-cases
• 🐛 Bugs / feature requests: GitHub issues
• ✉️ Commercial / higher limits: [email protected]

If you build something with the SDK, we’d love to see it — tag Tuxxin on whichever platform you post and we’ll boost it.