API Documentation

Everything you need to capture screenshots and generate OG images programmatically.

Getting Started

POST /v1/auth/register

Create a free API key. No authentication required. Rate limited to 5 requests/hour per IP.

Parameter	Type	Required	Description
`email`	string	Yes	Your email address (one key per email)

curl -X POST https://api.pixshot.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response:

{
  "api_key": "ps_live_abc123...",
  "key_id": "key_xyz789",
  "plan": "free",
  "email": "[email protected]",
  "warning": "Store this API key securely. It cannot be retrieved again."
}

Authentication

All API requests require an API key sent via the x-api-key header.

curl -X POST https://api.pixshot.dev/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_live_your_key_here" \
  -d '{"url": "https://example.com"}'

Upgrading Your Plan

To upgrade from the free tier, call the checkout endpoint with your API key:

curl -X POST https://api.pixshot.dev/v1/billing/checkout \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_live_your_key_here" \
  -d '{"plan": "pro"}'

Response: A checkout_url that redirects to the payment page. Plans: starter ($19/mo), pro ($49/mo), business ($99/mo).

Endpoints

POST /v1/screenshot

Capture a screenshot of a URL or render custom HTML.

Parameter	Type	Default	Description
`url`	string	-	URL to capture (required if no `html`)
`html`	string	-	Raw HTML to render (required if no `url`)
`format`	string	png	Output format: `png`, `jpeg`, `webp`
`viewport_width`	integer	1280	Viewport width (100-3840)
`viewport_height`	integer	720	Viewport height (100-2160)
`device_scale_factor`	number	2	Pixel density (1-3). Use 2 for retina-quality output
`full_page`	boolean	false	Capture full scrollable page
`device`	string	-	Device emulation (e.g. `iPhone 15`)
`selector`	string	-	CSS selector of element to capture (instead of viewport/full page)
`wait_for_selector`	string	-	CSS selector to wait for before capture
`wait_for_timeout`	integer	0	Delay in ms before capture (0-10000). Useful for lazy-loaded content
`dark_mode`	boolean	false	Emulate `prefers-color-scheme: dark`
`block_ads`	boolean	false	Block ads and trackers for cleaner screenshots
`dismiss_cookie_banners`	boolean	true	Auto-dismiss cookie consent banners before capture
`custom_css`	string	-	CSS to inject before capture. Pro+ only
`headers`	object	-	Custom HTTP headers (max 10). Starter+ only
`cookies`	array	-	Cookies to set: `[{name, value, domain}]` (max 20). Starter+ only
`use_proxy`	boolean	false	Route through a residential proxy to bypass datacenter IP blocks. Each proxied screenshot counts as 3 against your quota. Pro+ only
`proxy`	object	-	Use your own proxy: `{server, username?, password?}`. Server must be http, https, or socks5. Starter+ only

Response: Binary image with appropriate Content-Type header.

// Node.js example
const response = await fetch('https://api.pixshot.dev/v1/screenshot', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'ps_live_your_key_here',
  },
  body: JSON.stringify({
    url: 'https://github.com',
    format: 'webp',
    viewport_width: 1440,
    full_page: true,
  }),
});

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

POST /v1/og-image

Generate an OG image (1200x630) from a template.

Parameter	Type	Default	Description
`template.title`	string	-	Required. Main heading text
`template.subtitle`	string	-	Subheading text
`template.logo_url`	string	-	URL to logo image
`template.background_color`	string	#0f172a	Hex color for background
`template.text_color`	string	#f8fafc	Hex color for text
`template.font_size`	integer	64	Title font size (16-128)

Response: PNG image (1200x630).

curl -X POST https://api.pixshot.dev/v1/og-image \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_live_your_key_here" \
  -d '{
    "template": {
      "title": "How to Build a SaaS in 2026",
      "subtitle": "A practical guide for indie developers",
      "background_color": "#1e1b4b",
      "text_color": "#e0e7ff"
    }
  }' --output og.png

GET /v1/usage

Check your current usage and remaining quota.

curl https://api.pixshot.dev/v1/usage \
  -H "x-api-key: ps_live_your_key_here"

Response:

{
  "plan": "free",
  "period": "2026-02-01",
  "usage": {
    "screenshots": 142,
    "og_images": 28,
    "total": 170
  },
  "limits": {
    "monthly": 500,
    "remaining": 330,
    "rate_per_minute": 10
  }
}

GET /v1/health

Health check endpoint. No authentication required.

curl https://api.pixshot.dev/v1/health

Response Headers

Header	Description
`X-PixShot-Plan`	Your current plan tier
`X-PixShot-Cache`	`HIT` or `MISS` — whether the result was served from cache

Error Codes

Status	Meaning
`400`	Bad request — invalid parameters or SSRF-blocked URL
`401`	Missing or invalid API key
`403`	Feature requires a higher plan (e.g. custom_css on free tier)
`429`	Rate limit exceeded or monthly quota reached
`500`	Screenshot generation failed (timeout, invalid page, etc.)

Rate Limits

Plan	Monthly Quota	Rate Limit
Free	500	10 req/min
Starter ($19/mo)	5,000	30 req/min
Pro ($49/mo)	25,000	60 req/min
Business ($99/mo)	100,000	120 req/min