Screenshot API Reference

Complete REST API reference for capturing screenshots.

Base URL

base-url

https://api.stack0.dev/v1

Authentication

All API requests require authentication using your API key:

authentication

curl -X POST https://api.stack0.dev/v1/webdata/screenshots \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

POST/webdata/screenshots

Create a new screenshot capture request.

Request Body

Field	Type	Description
url	string	URL to capture (required)
format	string	png, jpeg, webp, or pdf
quality	number	Quality 0-100 (jpeg/webp only)
fullPage	boolean	Capture full page scroll
deviceType	string	desktop, tablet, or mobile
viewportWidth	number	Custom viewport width
viewportHeight	number	Custom viewport height
selector	string	Capture specific element
blockAds	boolean	Block advertisements
blockCookieBanners	boolean	Block cookie consent popups
darkMode	boolean	Enable dark mode
waitForSelector	string	Wait for element
waitForTimeout	number	Wait time in ms

create-screenshot

curl -X POST https://api.stack0.dev/v1/webdata/screenshots \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "fullPage": true,
    "blockAds": true
  }'
 
# Response
{
  "id": "scr_abc123",
  "status": "pending"
}

GET/webdata/screenshots/:id

Get a screenshot by ID.

get-screenshot

curl https://api.stack0.dev/v1/webdata/screenshots/scr_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "scr_abc123",
  "url": "https://example.com",
  "status": "completed",
  "format": "png",
  "fullPage": true,
  "deviceType": "desktop",
  "imageUrl": "https://cdn.stack0.dev/screenshots/scr_abc123.png",
  "imageSize": 245632,
  "imageWidth": 1920,
  "imageHeight": 4500,
  "processingTimeMs": 2340,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:02Z"
}

GET/webdata/screenshots

List screenshots with optional filters.

Query Parameters

Parameter	Type	Description
status	string	Filter by status
url	string	Filter by URL
limit	number	Max results (default 20)
cursor	string	Pagination cursor

list-screenshots

curl "https://api.stack0.dev/v1/webdata/screenshots?status=completed&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "items": [...],
  "nextCursor": "cursor_xyz"
}

DELETE/webdata/screenshots/:id

Delete a screenshot.

delete-screenshot

curl -X DELETE https://api.stack0.dev/v1/webdata/screenshots/scr_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "success": true }

Batch Screenshots

POST/webdata/batch/screenshots

Create a batch screenshot job for multiple URLs.

batch-screenshots

curl -X POST https://api.stack0.dev/v1/webdata/batch/screenshots \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://example.org",
      "https://example.net"
    ],
    "config": {
      "format": "png",
      "fullPage": true
    }
  }'
 
# Response
{
  "id": "batch_abc123",
  "status": "pending",
  "totalUrls": 3
}

GET/webdata/batch/:id

Get a batch job by ID.

get-batch-job

curl https://api.stack0.dev/v1/webdata/batch/batch_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "batch_abc123",
  "type": "screenshot",
  "status": "completed",
  "totalUrls": 3,
  "processedUrls": 3,
  "successfulUrls": 3,
  "failedUrls": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z"
}

POST/webdata/batch/:id/cancel

Cancel a running batch job.

cancel-batch-job

curl -X POST https://api.stack0.dev/v1/webdata/batch/batch_abc123/cancel \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "success": true }

Scheduled Screenshots

POST/webdata/schedules

Create a recurring screenshot schedule.

create-schedule

curl -X POST https://api.stack0.dev/v1/webdata/schedules \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily homepage screenshot",
    "url": "https://example.com",
    "type": "screenshot",
    "frequency": "daily",
    "config": {
      "format": "png",
      "fullPage": true
    },
    "detectChanges": true,
    "changeThreshold": 5
  }'
 
# Response
{ "id": "sch_abc123" }

POST/webdata/schedules/:id/toggle

Toggle a schedule on or off.

toggle-schedule

curl -X POST https://api.stack0.dev/v1/webdata/schedules/sch_abc123/toggle \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "isActive": false }

Status Values

Status	Description
pending	Job queued, waiting to start
processing	Job is currently running
completed	Job finished successfully
failed	Job encountered an error

Screenshots SDK Extraction API Error Handling