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.

not callable yet

Direct API access is not open during the beta. API keys created in the dashboard authenticate nothing — no request anywhere is accepted with one — and screenshots are captured from the dashboard instead.

These pages describe the capture service the dashboard talks to. Read every request below as the shape of the interface that will open, not as a call you can make today.

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: 1440

Viewport width in CSS pixels, 320–1920.

heightintegerdefault: 900

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 Tor. The page is fetched through the Tor network rather than directly from our network, and retries may fall back to a pool of public proxies. The exit node 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://api.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 during beta.

← Authentication Check job status →