API reference

Create screenshot job

POST/api/v1/screenshots

Queues a capture job and reserves one credit. Returns 202 Accepted with the job UUID and a status URL to poll.

Request body

urlstringrequired

Public http(s) URL to capture, up to 2048 characters. Private and internal network addresses are blocked.

modestringdefault: viewport

viewport captures the visible area; full_page scrolls and stitches the entire document.

widthintegerdefault: 1280

Viewport width in CSS pixels, 320–1920.

heightintegerdefault: 800

Viewport height in CSS pixels, 320–1080. For full_page this is the initial viewport only.

formatstringdefault: png

Output format: png, jpeg, or webp.

Captures egress through third-party proxies. The page is fetched through an anonymising proxy network rather than directly from our network, and retries may fall back to a pool of public proxies. The exit point belongs to a third party: for an https target it sees the hostname only, but for an http target it sees the whole request and response in plaintext. Prefer https, and never put credentials, session tokens, or signed one-time links in a URL you submit. Full detail in the Privacy Policy.

Example

curl

curl -X POST "https://previewapi.dev/api/v1/screenshots" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "mode": "viewport",
    "width": 1280,
    "height": 800,
    "format": "png"
  }'

response · 202

{
  "success": true,
  "job_uuid": "a818dd25-d93e-4148-8aed-9ebb109ceeda",
  "status": "queued",
  "status_url": "/api/v1/screenshots/a818dd25-d93e-4148-8aed-9ebb109ceeda"
}

Credits: submitting reserves 1 credit. It is consumed on completion and refunded automatically if the job fails.

← Authentication Check job status →