Documentation

Authentication

Pass your API key in the X-Api-Key header on every request.

curl https://api.scrnr.io/v1/screenshot \
  -H "X-Api-Key: sk_live_xxxx"

Endpoints

{
  "url": "https://example.com",        // required
  "delivery": "inline" | "url",        // default: inline
  "options": {  
    "width": 1280,                      // default: 1280, max varies by plan
    "height": 800,                       // default: 800, max varies by plan
    "fullPage": false,                   // default: false
    "format": "png" | "jpeg" | "webp", // default: png
    "waitFor": "load" | "networkidle", // default: load
    "delay": 0,                         // ms, max varies by plan
    "blockCookieBanners": false,        // default: false
    "headers": {"X-Custom": "value"},   // Pro plan only
    "retentionHours": 168              // Pro plan only, 1–720
  }
}

curl https://api.scrnr.io/v1/upload \
  -H "X-Api-Key: sk_live_xxxx" \
  -F "file=@./screenshot.png"

{
  "url": "https://storage.scrnr.io/screenshots/...",
  "expiresAt": "2026-05-20T12:00:00.000Z"  // null if covered by storage allowance
}

Cookie Banner Bypass

Set options.blockCookieBanners: true to suppress GDPR/consent overlays before the screenshot is captured.

{
  "url": "https://example.com",
  "options": {
    "blockCookieBanners": true
  }
}

No technique covers 100% of sites. For best results combine with waitFor: "networkidle" and a small delay.

Custom Request Headers Pro

Pass extra HTTP headers to the target page — useful for capturing authenticated pages, A/B test variants, or geo-specific content. Available on the Pro plan.

{
  "url": "https://example.com/dashboard",
  "options": {
    "headers": {
      "X-Tenant-Id": "acme",
      "Referer": "https://app.example.com"
    }
  }
}

Limits:

• Up to 20 headers per request
• 1 KB per value, 4 KB total across all headers
• The following headers are blocked: Host, Cookie, Authorization, Content-Length, hop-by-hop headers (Connection, Transfer-Encoding, etc.), and any header starting with Proxy-

Custom File Retention Pro

Override how long the captured file is retained for a single request. Useful for ephemeral previews (set lower) or short-term archival (set higher). Available on the Pro plan; ignored when delivery: "inline".

{
  "url": "https://example.com",
  "delivery": "url",
  "options": {
    "retentionHours": 1 // file deleted after 1 hour
  }
}

Range: 1–720 hours (up to 30 days). Setting retentionHoursalways wins — even on captures that would otherwise be kept indefinitely under your plan's included storage. For indefinite retention without a per-request override, the Pro plan includes 5 GB of permanent storage; the +25 GB storage add-on stacks on top.

Webhook Delivery Pro

Set delivery: "webhook" to have the captured file URL pushed to your server after the screenshot completes. Configure one HTTPS endpoint per account at /dashboard/webhooks — it fires for every capture by your account, whether triggered via API key or OAuth. We'll show the HMAC secret once at creation; save it.

The HTTP response returns immediately with 202 Accepted and the screenshot ID; the webhook fires asynchronously from the worker. Failed POSTs retry with exponential backoff at 30s, 5m, 30m, 2h, 12h (5 retries, ~14.5 hours). After max attempts or any non-retryable 4xx, the delivery is marked DEAD and surfaced for manual replay in the dashboard.

Payload

{
  "id": "clx9z2...",              // event id; matches X-Scrnr-Event-Id header
  "type": "screenshot.completed",
  "createdAt": "2026-04-28T12:00:00.000Z",
  "data": {
    "id": "clx9z2...",            // request id
    "url": "https://example.com",
    "fileUrl": "https://storage.scrnr.io/...",
    "expiresAt": "2026-05-05T12:00:00.000Z",
    "format": "png",
    "fileSizeBytes": 123456,
    "durationMs": 1234
  }
}

Verifying the signature

Each request includes an X-Scrnr-Signature header in the format t=<ts>,v1=<hex>. Recompute the HMAC-SHA256 of <ts>.<raw-body> using your endpoint secret and compare with v1 using a constant-time check. Reject requests where the timestamp is more than 5 minutes off.

import crypto from "node:crypto";

function verify(secret, signatureHeader, timestamp, rawBody) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const provided = signatureHeader.match(/v1=([^,]+)/)?.[1] ?? "";
  return (
    expected.length === provided.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided)) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  );
}

Headers

• X-Scrnr-Event-Id — stable across retries; use as your idempotency key
• X-Scrnr-Signature — t=<unix-seconds>,v1=<hex-hmac>
• User-Agent — scrnr-webhooks/1.0

Reply with 2xx to acknowledge. Anything else is treated as a failure (4xx are terminal except 408 / 425 / 429; 5xx and network errors retry on schedule).

Errors

All errors return JSON with an error field. Validation failures additionally include a details object from Zod.

Failed individual captures (5xx) do not count toward your monthly quota. Quota counters only increment on successful captures.

MCP Integration

Add scrnr as an MCP server to use take_screenshot and get_usage directly inside your AI tool.

https://mcp.scrnr.io/mcp

{
  "mcpServers": {
    "scrnr": {
      "url": "https://mcp.scrnr.io/mcp"
    }
  }
}

{
  "mcpServers": {
    "scrnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.scrnr.io/mcp",
        "--header",
        "Authorization: Bearer sk_live_xxxx"
      ]
    }
  }
}

{
  "mcpServers": {
    "scrnr": {
      "url": "https://mcp.scrnr.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_xxxx"
      }
    }
  }
}

Limits

Limits are enforced per request and per calendar month based on your plan.

Higher limits are available on paid plans. Manage your subscription and the optional +25 GB storage add-on from /dashboard/billing. Files captured while a storage allowance is active are kept indefinitely instead of expiring at the plan's retention window.