Skip to main content
POST
Synchronous capture
Send a JSON body to https://screenshotly.app/api/screenshot with an API key in x-api-key or Authorization: Bearer <key>. The response body is the capture itself unless you request persisted delivery.
The request body is limited to 64 KiB. The schema is strict: an unknown top-level field returns 400, so check spelling before assuming an option is unsupported. The machine-readable contract is the OpenAPI 3.1 document at https://screenshotly.app/api/openapi.json.

Core fields

Page navigation times out after 30 seconds.

Plan-gated fields

A request that uses a feature outside the workspace owner’s plan returns 403 with "error": "Plan upgrade required" and a minimumPlan value. HTML and WebM output cannot be combined with selector, clip, or mockup. Mockups apply only to png, jpeg, and webp output.

Nested objects

  • aiRemoval.types: any of cookie-banner, newsletter, chat-widget, social-overlay, ad. An empty list means all five.
  • aiRemoval.confidence: 0–1, default 0.8. Only detections at or above this score are removed.
  • scroll.distance: 100–50,000 px, default 5,000. scroll.speed: 100–5,000 px per second, default 500.
  • webhook.method: POST (default) or PUT. webhook.headers follows the same rules as headers.
  • These header names are rejected in headers and webhook.headers: Connection, Content-Length, Forwarded, Host, Proxy-Authorization, TE, Transfer-Encoding, Upgrade, X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto.

Responses

Capture bytes

A 200 response contains the file with a matching Content-Type (image/png, image/jpeg, image/webp, application/pdf, text/html, or video/webm) and these headers:

Persisted delivery

With "storage": { "enabled": true } the capture is stored for the workspace’s retention period (1–30 days) and the response is JSON instead of bytes:
The signed url is valid for 24 hours. duration is in milliseconds.

Errors

Error bodies are JSON with an error string and, usually, a message. Failed requests are recorded for diagnostics but do not consume your capture allowance. A response served from the cache is a successful capture and does.