Skip to main content

​
Endpoint

POST https://api.screenshotly.dev/api/v1/screenshots

​
Headers

HeaderRequiredDescription
screenshotly-api-keyYesYour API key
Content-TypeYesapplication/json

​
Request body

​
url
string
required
The URL of the webpage to capture.
​
format
string
default:"png"
Output format. Options: png, jpeg, webp.
​
width
integer
default:"1920"
Viewport width in pixels.
​
height
integer
default:"1080"
Viewport height in pixels.
​
fullPage
boolean
default:"false"
Capture the full scrollable page instead of just the viewport.
​
quality
integer
Image quality for JPEG and WebP (0-100). No effect on PNG.
​
delay
integer
default:"0"
Milliseconds to wait after page load before capturing.
​
deviceScaleFactor
number
default:"1"
Device pixel ratio. Use 2 for retina-quality screenshots.
​
isMobile
boolean
default:"false"
Emulate a mobile device.
​
hasTouch
boolean
default:"false"
Enable touch event support.
​
isLandscape
boolean
default:"false"
Use landscape orientation.
​
waitForSelector
string
CSS selector to wait for before capturing. The capture starts once this element exists in the DOM.
​
timeout
integer
default:"30000"
Maximum time in milliseconds to wait for the page to load.
​
cookies
array
Array of cookie objects to set before loading the page. Each object requires name, value, and domain.
​
localStorage
object
Key-value pairs to set in the page’s localStorage before capture.
​
headers
object
Custom HTTP headers to send with the page request.
​
webhookUrl
string
URL to receive a POST notification when the screenshot is ready.
​
name
string
Optional name for the screenshot.

​
Response

​
202 Accepted

The screenshot request was accepted and is being processed.
​
status
string
Always "processing" for a new request.
​
id
string
Unique identifier for this screenshot job. Use this to check status via the GET endpoint.
​
message
string
Confirmation message.
{
  "status": "processing",
  "id": "scr_abc123",
  "message": "Screenshot request accepted and is being processed."
}

​
Error responses

StatusDescription
400Bad request — missing or invalid parameters
401Unauthorized — invalid or missing API key
403Forbidden — insufficient permissions
429Too many requests — rate limit exceeded
500Internal server error
See error codes for details.

​
Examples

​
Basic capture

curl -X POST https://api.screenshotly.dev/api/v1/screenshots \
  -H "screenshotly-api-key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

​
Full-page JPEG with custom viewport

curl -X POST https://api.screenshotly.dev/api/v1/screenshots \
  -H "screenshotly-api-key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "jpeg",
    "quality": 85,
    "fullPage": true,
    "width": 1440,
    "height": 900
  }'

​
Mobile device with webhook

curl -X POST https://api.screenshotly.dev/api/v1/screenshots \
  -H "screenshotly-api-key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 390,
    "height": 844,
    "deviceScaleFactor": 3,
    "isMobile": true,
    "webhookUrl": "https://your-server.com/webhook"
  }'