API Documentation

Quick Start

Get started with the Previewr Screenshot API in minutes. All you need is an API key.

curl -X POST https://api.previewr.app/v1/screenshots/sync \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

Authentication

Authenticate your requests using the X-API-Key header.

curl -H "X-API-Key: sk_live_your_api_key" ...

Endpoints

POST/api/v1/screenshots/sync

Create a screenshot synchronously. Returns the image directly.

Request Body

{
  "url": "https://example.com",
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "options": {
    "full_page": false,
    "format": "png",
    "quality": 80,
    "delay_ms": 0,
    "wait_until": "networkidle"
  },
  "auth": {
    "cookies": [
      {
        "name": "session",
        "value": "abc123",
        "domain": ".example.com"
      }
    ],
    "headers": {
      "X-Custom-Header": "value"
    },
    "bearer_token": "your-token"
  }
}

Response

Returns the screenshot image with Content-Type: image/png (or the requested format).

POST/api/v1/screenshots

Create a screenshot asynchronously. Returns a task ID immediately.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "url": "https://example.com"
}
GET/api/v1/screenshots/:id

Get the status and result of a screenshot task.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com",
  "status": "completed",
  "screenshot_url": "https://cdn.previewr.app/screenshots/...",
  "processing_time_ms": 2340,
  "created_at": "2024-01-20T10:30:00Z",
  "completed_at": "2024-01-20T10:30:02Z"
}

Authentication Options

The Previewr API supports multiple authentication methods to capture protected pages:

Cookies

Pass session cookies to authenticate.

"auth": {
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": ".example.com",
      "path": "/",
      "secure": true,
      "http_only": true,
      "same_site": "Lax"
    }
  ]
}

Bearer Token

Pass a bearer token in the Authorization header.

"auth": {
  "bearer_token": "your-jwt-token"
}

Custom Headers

Pass custom headers for API key or other authentication.

"auth": {
  "headers": {
    "X-API-Key": "your-api-key",
    "X-Custom-Header": "value"
  }
}

Basic Auth

Pass username and password for HTTP Basic Authentication.

"auth": {
  "basic_auth": ["username", "password"]
}

Code Examples

Python

import requests

response = requests.post(
    "https://api.previewr.app/v1/screenshots/sync",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com",
        "auth": {
            "bearer_token": "your-token"
        }
    }
)

with open("screenshot.png", "wb") as f:
    f.write(response.content)

Node.js

import fs from 'fs';

const response = await fetch('https://api.previewr.app/v1/screenshots/sync', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    auth: {
      bearer_token: 'your-token'
    }
  })
});

const buffer = await response.arrayBuffer();
fs.writeFileSync('screenshot.png', Buffer.from(buffer));