API reference

Overview

ScreenNabster exposes /api/v1/capture for all capture types. The same option object works for GET and POST; only the encoding differs. Successful sync responses are raw bytes. Errors are JSON with error, code, and status.

Base URL for this environment: https://screennabster.com

All capture modes are also checked by ScreenNabster's prohibited-use policy before quota is consumed or rendering begins. Blocked targets, suspended accounts, or restricted high-risk features return 403 with a policy-specific error code.

ScreenshotOne-style aliases are documented in the migration guide.

Authentication

Header: X-API-Key: pk_…. Required on every call. Keys are created in the dashboard; inactive or unknown keys return 401.

For public GET links such as <img src>, use access_key, expires (Unix seconds), plus signature. The access key is the public ak_live_* identifier from the dashboard, not the private pk_* API key. The signature is HMAC-SHA256 over the exact query string without the signature parameter, using the signing secret shown once when creating the API key. The URL must not be expired: expires must be in the future and within 15 minutes of the server clock when the request arrives.

curl -X POST "https://screennabster.com/api/v1/capture" \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"https://example.com\"}" \
  --output out.png

Endpoint

POST https://screennabster.com/api/v1/capture

GET https://screennabster.com/api/v1/capture?…

POST body: JSON object. GET: query parameters with comma-separated arrays and JSON strings where noted in the parameter tables. ScreenNabster accepts its native option names and ScreenshotOne-compatible aliases for common migration paths.

Bulk captures

Use POST /api/v1/capture/bulk for up to 20 synchronous captures. Shared options are merged into each request, and per-request values win. The optional optimize flag (body root, options, or per-request) is accepted for ScreenshotOne migration compatibility and is currently a no-op.

{
  "execute": true,
  "options": {
    "format": "png",
    "viewport_width": 1440
  },
  "requests": [
    { "url": "https://example.com" },
    { "url": "https://example.org", "format": "webp" }
  ]
}

Set execute=false to generate signed public capture URLs instead of rendering immediately. Generated URLs include access_key, expires, and signature, so they can be embedded without an X-API-Key header.

curl -X POST "https://screennabster.com/api/v1/capture/bulk" \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d "{\"execute\":false,\"options\":{\"format\":\"png\"},\"requests\":[{\"url\":\"https://example.com\"}]}"

Target

Output

Viewport & device

Page behaviour

Appearance & scripting

PDF options

Cookies

Blocking & filters

Geolocation

Browser & HTTP

Caching & async

Internal

Async jobs & webhooks

Set background: true. The API responds immediately with:

{
  "job_id": "uuid",
  "status": "queued",
  "message": "Render queued. Results will be sent to your callback_url."
}

Basic auth credentials are stripped before the job is persisted — only the running worker session receives them. When rendering finishes, our backend uploads the binary to private storage, creates a time-limited signed URL, and POSTs to your callback_url if provided. Failed render events are sent only when webhook_errors is true. If a job cannot be persisted or accepted by the worker after quota is consumed, quota is released.

Webhook headers:

• Content-Type: application/json
• X-ScreenNabster-Signature: sha256=<hex> — HMAC-SHA256 of the raw body using SCREENNABSTER_WEBHOOK_SIGNING_SECRET on our side; verify with the same secret on yours (timing-safe compare).
• X-ScreenNabster-External-Identifier — present when you set external_identifier.

Success payload shape:

{
  "event": "capture.completed",
  "job_id": "uuid",
  "created_at": "2026-04-11T12:00:00.000Z",
  "result_url": "https://…signed…",
  "external_identifier": "customer-job-7"
}

Failure payload shape:

{
  "event": "capture.failed",
  "job_id": "uuid",
  "created_at": "2026-04-11T12:00:00.000Z",
  "error": "Worker error message",
  "error_code": "RENDER_ERROR",
  "external_identifier": "customer-job-7"
}

Webhook delivery is attempted once. Only 2xx responses mark callback_sent_at; non-2xx responses and network failures count as attempts but are not retried automatically yet.

Error codes

JSON body: { "error": string, "code": string, "status": number }. The HTTP status code matches status.