Create a capture

Send Content-Type: application/json and your key in X-Api-Key. A successful capture answers 200; there is no 202 and no polling loop, so the connection stays open for as long as the page takes to render.

url is the only required field. Every other field has a default, and the defaults endpoint will tell you what they currently are.

curl -X POST https://api.websitescreenshotworld.com/instant-snap/v1/captures \
  -H "X-Api-Key: $WSW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

That gives you a 1920×1080 desktop PNG with advertising and pop-ups blocked, described by a JSON envelope.

response_type is the field that changes the shape of the response, so decide it first.

The default, and the right choice when your code wants to know about the capture — its dimensions, how long it took, what HTTP status the page itself returned — as well as fetch the file.

{
  "success": true,
  "id": "0f9d1a6c-3b2e-4f18-8c6a-1d4b7e9a2c05",
  "status": "succeeded",
  "response_type": "json",
  "media_category": "image",
  "format": "png",
  "content_type": "image/png",
  "size_bytes": 184203,
  "width": 1920,
  "height": 1080,
  "duration_ms": 3184,
  "page_http_status": 200,
  "captured_at": "2026-09-01T09:14:22.000Z",
  "final_url": null,
  "media_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "download_url": "https://cdn.websitescreenshotworld.com/...",
  "expires_at": "2026-09-02T09:14:22.000Z",
  "page_source": null,
  "s3_delivery": null,
  "callback_url": null,
  "error_code": null,
  "spec_version": "v1"
}

The response body is the file itself, with the metadata moved into response headers. Use it when you are piping the bytes somewhere directly and never want a second round trip.

curl -X POST https://api.websitescreenshotworld.com/instant-snap/v1/captures \
  -H "X-Api-Key: $WSW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "response_type": "by_format",
    "format": "webp"
  }' \
  --output homepage.webp

HTTP/1.1 200 OK
Content-Type: image/webp
X-InstantSnap-Id: 0f9d1a6c-3b2e-4f18-8c6a-1d4b7e9a2c05
X-InstantSnap-Status: succeeded
X-InstantSnap-Width: 1920
X-InstantSnap-Height: 1080
X-InstantSnap-Size-Bytes: 96114
X-InstantSnap-Duration-Ms: 2914
X-InstantSnap-Page-Http-Status: 200
X-InstantSnap-Spec-Version: v1
X-InstantSnap-Captured-At: 2026-09-01T09:14:22.000Z
X-InstantSnap-Sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-InstantSnap-Part-Count: 1

An inline response is capped at 64 MiB. A capture larger than that answers 413 payload_too_large; ask for json or cloud_storage instead, neither of which has to fit in a response body.

A page-content capture answers with the text itself: text/markdown; charset=utf-8 or text/plain; charset=utf-8.

The capture is written straight into an S3-compatible bucket you control, and the envelope reports where it landed. Requires an s3_delivery block in the request — Deliver to your S3 bucket covers the credentials, the key layout and what happens when the write fails.

Add a page_source block and the same run saves the page's own markup beside the capture. Sending the block is the whole instruction:

{
  "url": "https://example.com/pricing",
  "response_type": "json",
  "page_source": { "format": "html" }
}

The answer carries a page_source block of its own, with a link that expires when the capture's does:

"page_source": {
  "format": "html",
  "content_type": "text/html",
  "size_bytes": 48211,
  "sha256": "3b1f8a0c5d9e2470ab6c1e83f5d2a7c40918e6b3d5a2f7c81b0e94d6a3f27c15",
  "download_url": "https://cdn.websitescreenshotworld.com/..."
}

A mobile, full-page capture of a pricing page, with the cookie banner dismissed and a timestamp burned into the corner:

{
  "url": "https://example.com/pricing",
  "response_type": "json",
  "media_category": "image",
  "format": "png",
  "device_category": "mobile",
  "emulated_device": "iPhone 13",
  "scroll_mode": "scroll",
  "auto_height": true,
  "max_height": 12000,
  "block_ads": true,
  "block_pop_ups": true,
  "page_timeout_ms": 45000,
  "scrolling_delay_ms": 2500,
  "locale": "en-GB",
  "time_zone": "Europe/London",
  "selectors": {
    "hide": "#cookie-banner, .newsletter-modal",
    "click": "#accept-all"
  },
  "timestamp_watermark": {
    "enabled": true,
    "location": "bottom"
  }
}

Every field here is described in Request parameters, including which of them your plan has to include.

A json or cloud_storage capture does not need you to hold the connection open. Add "async": true and the API answers at once with 202 Accepted, a Location header and the capture with status: queued; the capture runs as soon as a browser is free. Read it back with GET /captures/{id} until it is no longer queued or running, or send a callback_url and receive the result as a webhook.

curl -i -X POST https://api.websitescreenshotworld.com/instant-snap/v1/captures \
  -H "X-Api-Key: $WSW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/annual-report",
    "media_category": "pdf",
    "async": true,
    "timeout": 240
  }'

HTTP/1.1 202 Accepted
Location: /instant-snap/v1/captures/0f9d1a6c-3b2e-4f18-8c6a-1d4b7e9a2c05

{
  "success": true,
  "id": "0f9d1a6c-3b2e-4f18-8c6a-1d4b7e9a2c05",
  "status": "queued",
  "response_type": "json",
  "media_category": "pdf",
  "format": "pdf",
  "download_url": null,
  "error_code": null,
  ...
}

• timeout is the browser time the capture may use, every attempt included: 30–300 seconds, 120 when you leave it out. Time spent waiting in the queue does not count against it. It is accepted only with async.
• A capture that has not started within 15 minutes of being accepted ends failed with capture_expired and is not charged.
• Up to 100 async captures per workspace may be waiting or running at once. Past that the request is refused with 429 queue_full and nothing is queued or charged.
• Everything that refuses a synchronous request — validation, key, plan, quota, the per-minute limit — refuses an async one the same way, before anything is queued. The charge happens when the capture succeeds, as it always does.
• An Idempotency-Key works as for any capture, and a retry never queues it twice: it is answered 202 Accepted with the capture's Location and its current state — queued, running, finished or failed — and Idempotent-Replayed: true. A capture that never ran (queue_full, capture_expired) releases the key, so the retry queues it again.

• The request is synchronous. Set your own HTTP client timeout above page_timeout_ms plus a margin, or your client will give up on a capture that is still working. Every answer, including a wait_for_sync delivery, leaves within 2 minutes, so a client timeout of 130 seconds never cuts one off. The capture itself gets at most 100 seconds; one that could not be stored and answered within the 2 minutes ends as 504 capture_timeout and is not charged. For a page that needs longer, use an async capture: the request is answered at once and the capture may use up to 300 seconds.
• page_timeout_ms defaults to 30 000 and accepts 1 000–60 000. A page that never settles answers 504 capture_timeout.
• A full-page capture waits scrolling_delay_ms at each step, so a long page costs noticeably more wall-clock time than a viewport capture of the same site.
• 503 capture_busy means the renderer is saturated, not that your request was wrong. Retry it after the retry_after_seconds the error gives you.

Send an Idempotency-Key header (up to 255 printable characters, a UUID is ideal) and a retry with the same key and the same body never captures or charges twice. Keys are kept for 24 hours per account. The official client libraries send one on every capture for you.

• If the first request finished, the retry gets its answer: the capture (with a fresh download_url), or the same error it ended with. The response carries Idempotent-Replayed: true.
• If the first request is still running, the retry gets 409 idempotency_key_in_use with retry_after_seconds; wait and send it again.
• The same key with a different body, or for a by_format capture (whose file is not kept to hand back), gets 409 idempotency_key_reused.
• A request refused before anything ran (validation, key, quota, a busy renderer) does not use up the key: retry it as it is.