Screenshot Endpoint

POST /screenshot

Capture a screenshot of any URL. Returns the image binary data in the requested format, or a JSON response when using R2 storage.

Request

Headers

Header Required Description
X-API-Key Yes Your API key
Content-Type Yes Must be application/json

Body

JSON object with the following properties:

{
  "url": "https://example.com",
  "format": "png",
  "quality": 80,
  "fullPage": false,
  "device": "desktop",
  "width": 1920,
  "height": 1080,
  "scale": 1,
  "hideCookieBanners": true,
  "hidePopups": false,
  "blockAds": false,
  "blockRequests": []
}

See Parameters for the full list of options including selectors, custom headers, cookies, and R2 storage.

Response

Direct Response (default)

Returns the screenshot as binary data with the appropriate content type:

  • image/png for PNG format
  • image/jpeg for JPEG format
  • image/webp for WebP format
  • application/pdf for PDF format

R2 Storage Response

When storage: "r2" is set, returns a JSON response with the uploaded file details:

{
  "success": true,
  "storage": "r2",
  "url": "https://your-bucket.r2.dev/screenshots/20250130-143022-a1b2c3d4.png",
  "bucket": "your-bucket",
  "key": "screenshots/20250130-143022-a1b2c3d4.png"
}

Response Headers

Every response includes rate limit and quota information:

Header Description
X-Plan Your current plan name (free, starter, pro)
X-RateLimit-Limit Requests allowed per minute
X-RateLimit-Remaining Requests remaining in current minute
X-RateLimit-Reset Unix timestamp when rate limit resets
X-Quota-Limit Monthly screenshot quota
X-Quota-Remaining Screenshots remaining this billing period
X-Quota-Reset Unix timestamp when quota resets

Example Response Headers

HTTP/2 200
content-type: image/png
x-plan: starter
x-ratelimit-limit: 15
x-ratelimit-remaining: 12
x-ratelimit-reset: 1706745660
x-quota-limit: 2000
x-quota-remaining: 1847
x-quota-reset: 1709424000

Examples

Basic Screenshot

curl -X POST "https://api.shotone.io/screenshot" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://google.com",
    "format": "png",
    "fullPage": true,
    "device": "desktop"
  }' \
  --output screenshot.png

Upload to R2

curl -X POST "https://api.shotone.io/screenshot" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "storage": "r2",
    "r2CredentialId": "clxxx..."
  }'

Health Check

GET /health

Check if the API is running. No authentication required.

{
  "status": "ok"
}

Returns 200 OK with {"status": "ok"} when the service is healthy.

CORS

The API supports cross-origin requests with the following CORS policy:

Header Value
Access-Control-Allow-Origin *
Access-Control-Allow-Methods GET, POST, OPTIONS
Access-Control-Allow-Headers Content-Type, X-API-Key
Access-Control-Expose-Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Plan

Preflight OPTIONS requests are handled automatically. Rate limit and quota headers are exposed so you can read them from browser JavaScript.

Warning: While CORS allows browser requests, calling the API from client-side code exposes your API key. Always proxy requests through your own server in production.

Error Responses

See Error Codes for a complete list of error responses.

Tip: Use the Playground to build and test API requests visually — it generates the request code for you.