API reference

Authentication

Create a key in the dashboard under API keys. Send it as a bearer token. Keys start with sk_, are shown once and can be revoked at any time. Keep them on your server; never ship one in browser or mobile code.

Authorization: Bearer sk_…

Capture a screenshot

POST /v1/screenshots with a JSON body. The response body is the image. The X-Screenshot-Id and X-Expires-At headers identify the stored copy. Requests take a few seconds and time out after about 45 seconds.

curl --fail-with-body "https://your-domain.com/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","device":"desktop","format":"png"}' \
  -o screenshot.png

const response = await fetch(`https://your-domain.com/v1/screenshots`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCREENSHOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    device: "mobile",
    format: "webp",
    fullPage: true,
  }),
});
​
if (!response.ok) throw new Error((await response.json()).error.message);
​
const id = response.headers.get("X-Screenshot-Id");
const image = Buffer.from(await response.arrayBuffer());

Options

Unknown fields are rejected so typos do not silently change the result.

Devices

Pass any id as device. Sizes are CSS pixels, the same viewport the hardware reports. Phones, tablets and MacBooks are captured at 2x (sharp on Retina) unless fullPage is set. With frame the capture is placed inside sourced device artwork where available. Full-page captures always disable frames.

Retrieve a screenshot

Use the ID from the capture response. Metadata and image are only available to the key owner and until the expiry time.

curl "https://your-domain.com/v1/screenshots/$ID" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY"
​
curl "https://your-domain.com/v1/screenshots/$ID/image" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -o screenshot.png

{
  "id": "3f0c0f1e-…",
  "status": "succeeded",
  "options": { "url": "https://example.com/", "device": "desktop", "format": "png", "fullPage": false, "frame": false, "cleanup": true },
  "createdAt": "2026-11-10T09:00:00.000Z",
  "expiresAt": "2026-11-17T09:00:00.000Z"
}

status is succeeded, failed or, briefly while a capture is being finalized, pending or finalizing.

Errors

Errors are JSON with a stable code. Quote the requestId when reporting a problem.

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid capture options.",
    "requestId": "b9e1…"
  }
}

Limits and behavior

• Screenshots are private and expire seven days after creation.
• Images larger than 10 MB, and pages larger than 4096 px wide or 10,000 px tall in full-page mode, are rejected.
• Only public http and https addresses are captured. Private, loopback and internal hosts are refused.
• Cleanup is best effort. Some sites block automated browsers.
• There are no account quotas during launch, but the service can slow or refuse requests under load. Retry 503 and 504 with backoff.