API reference

https://shotwisp.com

All paths on this page are relative to the base URL. Uploads support single and batch routes; screenshots and PDFs each have a render route. Every endpoint requires an API key, which you create in the dashboard under API keys.

Each endpoint also has a dedicated page with Node.js and Python examples: /upload, /upload/batch, /screenshot, and /pdf.

1. Create an account (free, no card) and generate a key under API keys.
2. Send it on every request as Authorization: Bearer YOUR_API_KEY.
3. Make your first screenshot request:

curl -X POST https://shotwisp.com/api/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response": "json"}'

The response is capture metadata plus a hosted image URL:

{
  "id": "s3Nv8qLp5TkX2wYc",
  "url": "https://shotwisp.com/s/s3Nv8qLp5TkX2wYc",
  "format": "png",
  "width": 1440,
  "height": 900,
  "full_page": false,
  "duration_ms": 2140,
  "size_bytes": 208431
}

Drop "response": "json" to receive the PNG bytes directly instead.

Pass the key in the Authorization header of every request. Keys start with sw_ and are shown once, at creation — keep the value in an environment variable rather than in source control.

Authorization: Bearer sw_4f8a09c2e7b1d6a35f90c48e21b7d3aa64c1e8f2

# store the key once, e.g. in your shell profile or .env
export SHOTWISP_API_KEY="sw_4f8a09c2e7b1d6a35f90c48e21b7d3aa64c1e8f2"

# every request carries the same header
curl https://shotwisp.com/api/v1/screenshot \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response": "json"}'

Request

Send multipart/form-data with a file part. Uploads count against the monthly quota of your plan.

curl -X POST https://shotwisp.com/api/v1/upload \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -F "file=@./screenshot.png" \
  -F "expires_in=86400"

const form = new FormData();
form.append("file", file); // File or Blob
form.append("expires_in", "86400"); // optional

const res = await fetch("https://shotwisp.com/api/v1/upload", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SHOTWISP_API_KEY}` },
  body: form,
});

const upload = await res.json();
console.log(upload.url); // https://shotwisp.com/i/k7mwq2ax

Response

Success returns 201 Created. url is the share page, file_url serves the raw image, and delete_url removes the upload without further authentication. content_type is the type we detected in the bytes, which is not necessarily the one you sent.

{
  "id": "u7Kd2mXq9RfW4bZn",
  "slug": "k7mwq2ax",
  "url": "https://shotwisp.com/i/k7mwq2ax",
  "file_url": "https://shotwisp.com/f/k7mwq2ax",
  "delete_url": "https://shotwisp.com/api/uploads/u7Kd2mXq9RfW4bZn/delete?token=Fj3kW9sLq2Xv7Rp4Tz8mNc5d",
  "expires_at": "2026-08-11T14:05:00.000Z",
  "size_bytes": 481290,
  "content_type": "image/png",
  "filename": "screenshot.png"
}

Batch uploads

Repeat the file part to upload up to 10 images in one request, with at most 50 MB of combined file data. expires_in applies to every file in the batch, while the normal per-file plan limit and monthly upload quota still apply individually.

curl -X POST https://shotwisp.com/api/v1/upload/batch \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -F "file=@./first.png" \
  -F "file=@./second.jpg" \
  -F "expires_in=86400"

Results stay in request order. The endpoint returns 201 Created when every file succeeds, or 207 Multi-Status when some files succeed and others fail. Request-level authentication, parsing, size, and rate-limit failures retain their normal 4xx response.

{
  "items": [
    {
      "ok": true,
      "index": 0,
      "source_filename": "first.png",
      "upload": {
        "id": "u7Kd2mXq9RfW4bZn",
        "slug": "k7mwq2ax",
        "url": "https://shotwisp.com/i/k7mwq2ax",
        "file_url": "https://shotwisp.com/f/k7mwq2ax",
        "delete_url": "https://shotwisp.com/api/uploads/u7Kd2mXq9RfW4bZn/delete?token=Fj3kW9sLq2Xv7Rp4Tz8mNc5d",
        "expires_at": "2026-08-11T14:05:00.000Z",
        "size_bytes": 481290,
        "content_type": "image/png",
        "filename": "first.png"
      }
    },
    {
      "ok": false,
      "index": 1,
      "source_filename": "second.jpg",
      "error": {
        "code": "unsupported_type",
        "message": "Unsupported image type. The file's contents do not match a supported format."
      }
    }
  ],
  "summary": { "total": 2, "succeeded": 1, "failed": 1 }
}

Validation and serving

Files are validated by signature, not by filename or declared content type: a .png that does not carry PNG bytes is rejected with 415 unsupported_type. SVG uploads are sanitized before storage — scripts, event handlers, embedded objects, external entities, and off-document references are stripped, and the sanitized bytes are what we keep.

Request

Send a JSON body. Only url is required; everything else has a sensible default.

curl -X POST https://shotwisp.com/api/v1/screenshot \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "full_page": true, "format": "png"}' \
  -o shot.png

Response

By default the response streams the encoded image with the matching Content-Type. If the target page cannot be loaded, the request fails with 502 capture_failed — see Errors. Failed captures are not metered.

Set response to json to receive capture metadata instead of bytes. The url field is the hosted image — a link to the stored capture, not the page you captured.

curl -X POST https://shotwisp.com/api/v1/screenshot \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "width": 1280, "height": 800, "response": "json"}'

{
  "id": "s3Nv8qLp5TkX2wYc",
  "url": "https://shotwisp.com/s/s3Nv8qLp5TkX2wYc",
  "format": "png",
  "width": 1280,
  "height": 800,
  "full_page": false,
  "duration_ms": 2140,
  "size_bytes": 208431
}

Request

Send a JSON body. Only url is required. A successful PDF consumes one screenshot unit because it uses the same managed-browser render capacity.

curl -X POST https://shotwisp.com/api/v1/pdf \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "paper_format": "a4",
    "print_background": true,
    "margin": { "top": "0.5in", "right": "0.5in", "bottom": "0.5in", "left": "0.5in" }
  }' \
  -o page.pdf

Response

By default, the response streams application/pdf bytes. It carries x-shotwisp-id, render duration, quota, and rate-limit headers. Failed renders are not metered.

Set response to json for metadata and a hosted url that opens the stored PDF.

curl -X POST https://shotwisp.com/api/v1/pdf \
  -H "Authorization: Bearer $SHOTWISP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "landscape": true, "response": "json"}'

{
  "id": "p8Fm3qRt7VwK2xNc",
  "url": "https://shotwisp.com/p/p8Fm3qRt7VwK2xNc",
  "paper_format": "letter",
  "landscape": true,
  "print_background": true,
  "prefer_css_page_size": false,
  "scale": 1,
  "margin": { "top": 0, "right": 0, "bottom": 0, "left": 0 },
  "viewport": { "width": 1440, "height": 900 },
  "wait_until": "networkidle2",
  "delay_ms": 0,
  "duration_ms": 1840,
  "size_bytes": 42718
}

Successful calls carry your position in the current window, as do the 402 and 429 responses.

Once the budget is spent the API answers 429 rate_limited with Retry-After in seconds. Rejected requests are not metered and do not count against your monthly quota.

HTTP/1.1 429 Too Many Requests
Retry-After: 27
x-shotwisp-ratelimit-limit: 80
x-shotwisp-ratelimit-remaining: 0
x-shotwisp-ratelimit-reset: 27

{"error":{"code":"rate_limited","message":"Rate limit exceeded. Retry in 27s."}}

Wait at least Retry-After seconds, then back off exponentially with jitter. Retrying immediately on a fixed interval keeps you pinned at the limit.

async function callWithBackoff(send, attempts = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await send();
    if (res.status !== 429 || attempt === attempts - 1) return res;

    // Honour Retry-After, then back off exponentially with jitter.
    const retryAfter = Number(res.headers.get("retry-after")) || 1;
    const waitMs =
      Math.max(retryAfter, 2 ** attempt) * 1000 + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
}

Quotas reset on the first day of each calendar month at 00:00 UTC. Every plan accepts files up to 10 MB. Full plan details are on the pricing page.

Overages

With overages enabled, requests past quota succeed as normal and each extra unit is billed at your plan’s per-unit rate; the response carries x-shotwisp-overage: true so you can count billable units yourself. With overages disabled — the default — the API returns 402 quota_exceeded until the month rolls over or you upgrade. Free has no overage rate, so it always stops at the quota.

Usage headers

Every metered call — upload or screenshot, image bytes or JSON — reports your quota position as of that request, so you can react before the limit rather than after it.

HTTP/1.1 200 OK
Content-Type: image/png
x-shotwisp-id: s3Nv8qLp5TkX2wYc
x-shotwisp-ratelimit-limit: 80
x-shotwisp-ratelimit-remaining: 78
x-shotwisp-ratelimit-reset: 41
x-shotwisp-quota-limit: 10000
x-shotwisp-quota-remaining: 1180
x-shotwisp-quota-usage-percent: 88
x-shotwisp-quota-warning: 80

x-shotwisp-quota-warning appears at 80, 90, and 100 percent of quota; the same thresholds drive the dashboard warnings. A 402 quota_exceeded response still carries x-shotwisp-quota-limit and x-shotwisp-quota-remaining.

• Capture targets must be public http(s) URLs. Localhost, private and link-local IP ranges, cloud metadata endpoints, and other schemes are rejected with validation_error, and DNS is re-resolved and re-checked immediately before the browser dials out.
• During rendering, every request the page makes — redirect hops (maximum 5), iframes, and subresources — is re-validated against the same private-network rules, so a page cannot pull internal hosts into a capture.
• Your API key is never forwarded to the target page; the renderer sends no authentication of yours.
• Uploads are validated by byte signature rather than filename or declared type, and SVG files are sanitized (scripts, event handlers, and external references stripped) before storage.
• Stored files are served from an isolated origin with X-Content-Type-Options: nosniff; SVGs additionally carry a sandboxing Content-Security-Policy.
• The delete_url on uploads works without further authentication — treat it as a secret.

• The current version is v1; every path starts with /api/v1/. v1 URLs remain stable.
• Non-breaking changes — new optional parameters, new response fields, new endpoints — may ship at any time. Clients must tolerate unknown response fields.
• Breaking changes — removing or renaming fields, changing defaults, types, enums, error codes, or status codes — would ship under a new version path, with v1 kept working through a published migration window.
• Deprecations and migrations are announced in the changelog before they take effect.