API documentation

A single endpoint, explicit parameters. Authentication by API key (token).

Endpoint

GET https://webshotninja.com/api

Authentication

Add your API key as the token parameter. You'll find it in your dashboard.

https://webshotninja.com/api?token=YOUR_API_KEY&url=https://example.com

Parameters

Parameter	Default	Description
`token`	—	Your API key (required).
`url`	—	The URL of the page to capture, URL-encoded (required).
`width`	1600	Browser width in pixels (100–3840).
`height`	1200	Browser height in pixels (100–4320).
`full`	0	1 = capture the entire page height.
`format`	webp	png, jpeg or webp.
`quality`	80	jpeg/webp quality (1–100).
`delay`	0	Wait in milliseconds after page load (max 10000). Useful for sites with intro animations.
`nocookies`	1	1 = dismiss/hide cookie banners (default). 0 = capture the page as-is.
`scroll`	auto	1 = force lazy-loading auto-scroll, 0 = disable. Default: automatic when full=1.
`nocache`	0	1 = force a fresh capture (skip the 30-day cache).
`selector`	—	CSS selector to capture a specific element (e.g. #hero, .pricing-table). The element is awaited up to 10s. Returns 404 if not found. Overrides full if both are set.
`noads`	0	1 = block ads and trackers (powered by EasyList). Can be combined with nocookies.
`css`	—	Custom CSS injected into the page before capture (max 10 KB). API only, not available on the demo.
`js`	—	Custom JavaScript executed in the page context before capture (max 10 KB). API only. If the script throws, the capture still completes and the error is returned in the X-WSN-JS-Error header.
`dark`	0	1 = enable dark mode (prefers-color-scheme: dark). Only works if the target site supports native dark mode.
`device`	—	Device preset: iphone14, iphone14pro, pixel7, ipad, galaxys23. Sets viewport, user-agent and touch emulation. Explicit width/height override the device viewport.
`scale`	1	Device scale factor (1, 2 or 3). scale=2 produces a retina image (2x resolution, heavier file).

Code examples

curl

curl "https://webshotninja.com/api?token=YOUR_API_KEY&url=https%3A%2F%2Fexample.com&full=1&format=webp" -o shot.webp

PHP

$params = http_build_query([
    'token'  => 'YOUR_API_KEY',
    'url'    => 'https://example.com',
    'full'   => 1,
    'format' => 'webp',
]);
file_put_contents('shot.webp', file_get_contents('https://webshotninja.com/api?' . $params));

JavaScript (Node.js)

const params = new URLSearchParams({
  token: 'YOUR_API_KEY',
  url: 'https://example.com',
  full: '1',
  format: 'webp',
});
const res = await fetch('https://webshotninja.com/api?' + params);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));

Python

import requests

r = requests.get('https://webshotninja.com/api', params={
    'token': 'YOUR_API_KEY',
    'url': 'https://example.com',
    'full': 1,
    'format': 'webp',
})
open('shot.webp', 'wb').write(r.content)

Signed URLs

Embed capture URLs in your frontend (e.g. img src) without exposing your API key. Sign the sorted query string (all params except sig) with HMAC-SHA256 using your signing secret. Add user (your user ID), expires (Unix timestamp) and sig (the hex signature). The capture is served and counted against your quota. Your signing secret is in your dashboard.

GET https://webshotninja.com/api?url=https://example.com&user=USER_ID&expires=TIMESTAMP&sig=HMAC_SHA256_HEX

Node.js

const crypto = require('crypto');
const params = new URLSearchParams({
  url: 'https://example.com',
  user: 'YOUR_USER_ID',
  expires: String(Math.floor(Date.now()/1000) + 3600), // 1h
});
const sorted = [...params].sort((a,b) => a[0].localeCompare(b[0]))
  .map(([k,v]) => encodeURIComponent(k)+'='+encodeURIComponent(v)).join('&');
const sig = crypto.createHmac('sha256', 'YOUR_SIGNING_SECRET')
  .update(sorted).digest('hex');
const url = 'https://webshotninja.com/api?' + sorted + '&sig=' + sig;

PHP

$params = ['url' => 'https://example.com', 'user' => 'YOUR_USER_ID',
           'expires' => (string)(time() + 3600)];
ksort($params);
$qs = implode('&', array_map(fn($k,$v) => rawurlencode($k).'='.rawurlencode($v),
      array_keys($params), $params));
$sig = hash_hmac('sha256', $qs, 'YOUR_SIGNING_SECRET');
$url = 'https://webshotninja.com/api?' . $qs . '&sig=' . $sig;

HTML rendering

POST /api/render — render raw HTML to an image. Send a JSON body with a html field (max 2 MB) and your token. All screenshot parameters (width, height, format, css, js, selector, dark, device, scale…) are accepted. Ideal for generating Open Graph / social card images. API only, counts toward your quota.

POST https://webshotninja.com/api/render

curl -X POST https://webshotninja.com/api/render \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_API_KEY","html":"<h1>Hello</h1><p>Social card</p>","width":1200,"height":630,"format":"png"}' \
  -o card.png

Response

The raw image (Content-Type image/png, image/jpeg or image/webp). On error, a JSON object with an error field. The X-Cache header reads HIT (cached) or MISS (fresh capture).