API Documentation

Everything you need to integrate Pixcap's screenshot API into your application.

Introduction

Pixcap provides a simple REST API to capture high-quality screenshots of any public website. Make an HTTP request with a target URL, and receive a pixel-perfect screenshot in return.

Base URL

https://pixcap.dev/api/v1

Authentication

All API requests require authentication using an API key. You can pass your key in two ways:

Header (Recommended)

X-API-Key: pix_your_api_key_here

Query Parameter

?api_key=pix_your_api_key_here

Quick Start

Capture your first screenshot in seconds:

cURL

curl "https://pixcap.dev/api/v1/screenshot?url=https://github.com" \
  -H "X-API-Key: pix_your_api_key" \
  -o screenshot.png

Node.js

const response = await fetch(
  'https://pixcap.dev/api/v1/screenshot?url=https://github.com',
  { headers: { 'X-API-Key': 'pix_your_api_key' } }
);
const buffer = await response.arrayBuffer();
fs.writeFileSync('screenshot.png', Buffer.from(buffer));

Python

import requests

response = requests.get(
    'https://pixcap.dev/api/v1/screenshot',
    params={'url': 'https://github.com'},
    headers={'X-API-Key': 'pix_your_api_key'}
)

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

GET /screenshot

Capture a screenshot and receive the image directly in the response body.

Example

GET /api/v1/screenshot?url=https://stripe.com&width=1440&format=png

Response Headers

POST /screenshot

Capture a screenshot and receive a JSON response with base64-encoded image.

Request Body

{
  "url": "https://github.com",
  "width": 1920,
  "height": 1080,
  "format": "png",
  "fullPage": false
}

Response

{
  "success": true,
  "data": {
    "image": "iVBORw0KGgoAAAANSUhEUgAA...",
    "metadata": {
      "url": "https://github.com",
      "width": 1920,
      "height": 1080,
      "format": "png",
      "responseTimeMs": 2340,
      "timestamp": "2024-01-15T10:30:00.000Z"
    },
    "credits_remaining": 95
  }
}

Parameters

Advanced Options

Setting Cookies

Pass cookies to capture authenticated pages or maintain session state:

// POST request with cookies
{
  "url": "https://example.com/dashboard",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123xyz",
      "domain": "example.com"
    },
    {
      "name": "auth_token",
      "value": "Bearer_token_here",
      "domain": ".example.com",
      "path": "/"
    }
  ]
}

Blocking Elements

Hide modals, popups, banners, or any other elements before capturing:

// Hide cookie banners and modals
{
  "url": "https://example.com",
  "blockSelectors": [
    ".cookie-banner",
    ".newsletter-popup",
    "#modal-overlay",
    "[data-testid='promo-banner']"
  ]
}

Waiting for Content

Wait for dynamic content to load before capturing (useful for SPAs):

// Wait for main content to render
{
  "url": "https://spa-example.com",
  "waitForSelector": ".main-content-loaded",
  "delay": 500
}

Auto-Dismiss Cookie Consent

Automatically click common "Accept" buttons on cookie consent banners:

// Dismiss cookie banners automatically
{
  "url": "https://news-site.com",
  "dismissCookieConsent": true
}

This works with most major cookie consent providers including OneTrust, Cookiebot, and common custom implementations.

Bulk Screenshots

Capture screenshots of an entire website by providing a sitemap XML URL. Perfect for creating visual archives, monitoring site-wide changes, or generating preview images at scale.

Key Features

• Process up to 100 pages per job
• Concurrent processing for speed
• ZIP download with organized directory structure
• Credits pre-authorized and refunded for failures
• Manifest file with job metadata included
• 24-hour download window

Create Bulk Job

Submit a sitemap URL to start capturing screenshots of all pages.

Request Body

You can provide either a url (auto-detects sitemap) or sitemap_url (explicit sitemap):

// Option 1: Auto-detect sitemap (recommended)
{
  "url": "example.com",
  "options": { "maxPages": 50 }
}

// Option 2: Explicit sitemap URL
{
  "sitemap_url": "https://example.com/sitemap.xml",
  "options": { "maxPages": 50 }
}

Response

{
  "success": true,
  "data": {
    "job_id": "f147c641-f644-429c-8395-2ed9cdf30154",
    "status": "pending",
    "sitemap_url": "https://example.com/sitemap.xml",
    "total_urls": 42,
    "credits_reserved": 42,
    "credits_remaining": 58,
    "status_url": "/api/v1/bulk-screenshot/f147c641.../status"
  }
}

Check Job Status

Poll this endpoint to track the progress of your bulk screenshot job.

Response

{
  "success": true,
  "data": {
    "jobId": "f147c641-f644-429c-8395-2ed9cdf30154",
    "status": "completed",
    "sitemapUrl": "https://example.com/sitemap.xml",
    "progress": {
      "totalUrls": 42,
      "processed": 42,
      "successful": 40,
      "failed": 2,
      "percentage": 100
    },
    "credits": {
      "reserved": 42,
      "used": 40,
      "refunded": 2
    },
    "download": {
      "expiresAt": "2024-01-16T10:30:00.000Z",
      "fileSize": 15728640
    }
  }
}

Job Status Values

Download ZIP

Download the completed screenshot archive. Available for 24 hours after completion.

ZIP Structure

screenshots-example-com-2024-01-15/
  _manifest.json        # Job metadata and URL list
  index.png             # https://example.com/
  about/
    index.png           # https://example.com/about/
  blog/
    index.png           # https://example.com/blog/
    my-post.png         # https://example.com/blog/my-post

Example Workflow

# 1. Create a bulk job (sitemap auto-detected)
curl -X POST "https://pixcap.dev/api/v1/bulk-screenshot" \
  -H "X-API-Key: pix_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com", "options": {"maxPages": 20}}'

# 2. Check status (poll until completed)
curl "https://pixcap.dev/api/v1/bulk-screenshot/{job_id}/status" \
  -H "X-API-Key: pix_your_api_key"

# 3. Download ZIP when ready
curl "https://pixcap.dev/api/v1/bulk-screenshot/{job_id}/download" \
  -H "X-API-Key: pix_your_api_key" \
  -o screenshots.zip

VPN Connectors

Capture screenshots of internal websites without exposing them to the internet. Deploy a lightweight connector inside your network to screenshot private dashboards, staging environments, and internal applications.

Architecture

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Your App       │      │  Pixcap Cloud    │      │  Connector      │
│                 │      │                  │      │  (Your Network) │
└────────┬────────┘      └────────┬─────────┘      └────────┬────────┘
         │                        │                         │
         │ 1. API Request         │                         │
         │ with connector_id      │                         │
         │───────────────────────>│                         │
         │                        │                         │
         │                        │ 2. Route via WebSocket  │
         │                        │────────────────────────>│
         │                        │                         │
         │                        │              3. Capture screenshot
         │                        │                 of internal URL
         │                        │                         │
         │                        │ 4. Return image         │
         │                        │<────────────────────────│
         │                        │                         │
         │ 5. Screenshot response │                         │
         │<───────────────────────│                         │

Key Benefits

• Security – Internal apps stay private, only outbound connections needed
• No firewall changes – Works behind NAT and corporate firewalls
• Same pricing – 1 credit per screenshot, same as cloud
• Easy deployment – Single Docker command or npm install

Quick Start

Get up and running in under 5 minutes:

1. Create a Connector

Log in to your dashboard, scroll to the VPN Connectors section, and click "Create New Connector". Copy the token—it's only shown once.

2. Deploy the Connector

docker run -d \
  -e PIXCAP_CONNECTOR_TOKEN=pxc_your_token \
  --restart unless-stopped \
  --name pixcap-connector \
  dashah2/pixcap-connector

3. Take a Screenshot

Once your connector shows "Online" in the dashboard, make a request with your connector_id:

curl "https://pixcap.dev/api/v1/screenshot?url=http://internal.example.com&connector_id=conn_YOUR_ID" \
  -H "X-API-Key: pix_YOUR_API_KEY" \
  -o screenshot.png

Installation

Docker (Recommended)

docker run -d \
  -e PIXCAP_CONNECTOR_TOKEN=pxc_your_token \
  --restart unless-stopped \
  --name pixcap-connector \
  dashah2/pixcap-connector

Docker Compose

version: '3.8'
services:
  pixcap-connector:
    image: dashah2/pixcap-connector:latest
    environment:
      - PIXCAP_CONNECTOR_TOKEN=${PIXCAP_CONNECTOR_TOKEN}
    restart: unless-stopped

npm

npm install -g pixcap-connector
PIXCAP_CONNECTOR_TOKEN=pxc_your_token pixcap-connector

From Source

git clone https://github.com/dan-shah/pixcap.git
cd dashah2/pixcap-connector
npm install
PIXCAP_CONNECTOR_TOKEN=pxc_your_token npm start

Configuration

Configure the connector using environment variables:

API Reference

Use the connector_id parameter to route screenshot requests through your connector.

GET Request

curl "https://pixcap.dev/api/v1/screenshot?url=http://internal-app.local&connector_id=conn_abc123" \
  -H "X-API-Key: pix_your_api_key" \
  -o screenshot.png

POST Request

{
  "url": "http://internal-app.local:3000/dashboard",
  "connectorId": "conn_abc123",
  "width": 1920,
  "height": 1080
}

Connector Parameter

Response Headers

When a request is routed through a connector, an additional header is included:

Connector Error Codes

Manage Connectors

Create and manage connectors via API or dashboard.

List Connectors

Create Connector

{
  "name": "Office Network"
}

Delete Connector

Regenerate Token

Troubleshooting

Connector shows "Offline"

1. Check the connector is running: docker logs pixcap-connector
2. Verify your token is correct and hasn't been regenerated
3. Ensure outbound WebSocket connections are allowed (port 443)
4. Check for firewall rules blocking wss://pixcap.dev

Screenshots timeout

1. Increase SCREENSHOT_TIMEOUT environment variable
2. Check if the target URL is accessible from the connector host
3. Verify Chrome/Chromium is installed correctly
4. Test connectivity: docker exec pixcap-connector curl http://your-internal-url

Browser launch fails

Set the Chrome path explicitly:

# Linux
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

# macOS
PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Docker (usually auto-detected)
# The Docker image includes Chromium

Connection keeps dropping

1. The connector includes auto-reconnect with exponential backoff
2. Check for proxy or firewall issues with WebSocket connections
3. Review logs for disconnection reasons: docker logs -f pixcap-connector

Register

Create a new account and receive your API key.

Request

{
  "email": "you@company.com"
}

Response

{
  "success": true,
  "data": {
    "message": "Account created successfully",
    "email": "you@company.com",
    "api_key": "pix_a1b2c3d4e5f6...",
    "credits": 100
  }
}

API Keys

You can create up to 5 API keys per account.

Create New Key

Deactivate Key

Error Codes

Rate Limits

To ensure fair usage and platform stability:

Rate limit headers are included in all responses:

• X-RateLimit-Limit – Maximum requests allowed
• X-RateLimit-Remaining – Requests remaining
• X-RateLimit-Reset – When the limit resets