API Documentation

Node.js SDK
Authentication
Screenshot Endpoint
Premium Features
PDF Generation
Device Presets
Error Codes
Rate Limits

Node.js SDK

The easiest way to use ShotAPI is with our official Node.js SDK. It provides full TypeScript support, automatic retries with exponential backoff, and convenient helper methods.

Installation

npm install @shotapi/sdk

Quick Start

import ShotAPI from '@shotapi/sdk';

const client = new ShotAPI({ apiKey: 'YOUR_API_KEY' });

// Basic screenshot
const result = await client.screenshot({
  url: 'https://example.com'
});

console.log(result.url); // URL to the screenshot

SDK Features

Full Page Screenshot

const result = await client.screenshot({
  url: 'https://example.com',
  fullPage: true
});

Device Preset

const result = await client.screenshot({
  url: 'https://example.com',
  device: 'iphone-14-pro'
});

Save to File

await client.screenshotToFile(
  { url: 'https://example.com' },
  './screenshot.png'
);

Get as Buffer

const buffer = await client.screenshotBuffer({
  url: 'https://example.com'
});

Batch Screenshots

const results = await client.batch([
  'https://example.com',
  'https://google.com'
], { width: 1280 });

Premium Features

const result = await client.screenshot({
  url: 'https://example.com',
  selector: '#hero',
  blockAds: true
});

Configuration

const client = new ShotAPI({
  apiKey: 'YOUR_API_KEY',  // Required
  baseUrl: 'https://shotapi.dev', // Optional
  timeout: 30000,          // Request timeout in ms (default: 30000)
  retries: 2               // Retry attempts (default: 2)
});

Error Handling

import ShotAPI, { ShotAPIException } from '@shotapi/sdk';

try {
  const result = await client.screenshot({ url: 'https://example.com' });
} catch (error) {
  if (error instanceof ShotAPIException) {
    console.error('API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Status Code:', error.statusCode);
  }
}

View the full SDK documentation on npm or GitHub.

Authentication

All API requests require an API key. You can pass your API key in one of three ways:

Query parameter: ?api_key=YOUR_KEY
Header: X-API-Key: YOUR_KEY
Header: Authorization: Bearer YOUR_KEY

Screenshot Endpoint

GET/api/v1/screenshot

POST/api/v1/screenshot

Basic Parameters

Parameter	Type	Default	Description
`url`	string	required	URL to capture
`width`	number	1280	Viewport width (320-3840)
`height`	number	800	Viewport height (240-2160)
`full_page`	boolean	false	Capture full scrollable page
`format`	string	png	Output format: png, jpeg, webp, pdf
`quality`	number	90	Image quality (1-100, jpeg/webp only)
`delay`	number	0	Wait time in ms before capture (0-10000)
`block_ads`	boolean	false	Block advertisements
`block_cookie_banners`	boolean	true	Hide cookie consent popups
`dark_mode`	boolean	false	Emulate dark mode preference
`device_scale_factor`	number	1	Device pixel ratio (1-3)

Example Request (GET)

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&api_key=YOUR_KEY&width=1920&full_page=true"

Example Request (POST)

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1920,
    "full_page": true,
    "device": "desktop",
    "dark_mode": true
  }'

Example Response

{
  "success": true,
  "data": {
    "screenshot_url": "https://r2.shotapi.dev/screenshots/abc123.png",
    "width": 1920,
    "height": 3200,
    "format": "png",
    "file_size": 524288,
    "cached": false
  },
  "usage": {
    "credits_used": 43,
    "credits_limit": 500,
    "credits_remaining": 457
  }
}

Premium Features

The following features are available on paid plans only. Free plan users will receive a 403 error when trying to use these features.

Parameter	Type	Description
`device`	string	Device preset (desktop, mobile, tablet, iphone-14, etc.)
`selector`	string	CSS selector to capture specific element only
`hide_selectors`	string[]	CSS selectors of elements to hide (comma-separated for GET)
`custom_css`	string	Custom CSS to inject into the page (max 10KB)
`custom_js`	string	Custom JavaScript to execute (max 10KB)
`wait_for_selector`	string	Wait for element before capture (10s timeout)
`custom_headers`	object	Custom HTTP headers (POST only)
`user_agent`	string	Custom user agent string
`thumbnail`	object	Generate thumbnail: {width, height}
`extract_html`	boolean	Include page HTML in response
`clip`	object	Crop region: {x, y, width, height}

Example: Capture Specific Element

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "selector": "#main-content",
    "hide_selectors": [".ads", ".cookie-banner", ".popup"]
  }'

Example: Custom CSS Injection

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "custom_css": "body { background: #f0f0f0; } .header { display: none; }"
  }'

Example: Generate Thumbnail

curl -X POST https://shotapi.dev/api/v1/screenshot \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "thumbnail": { "width": 300, "height": 200 }
  }'

Response includes thumbnail_url in addition to the full screenshot.

PDF Generation

Generate PDF documents from any webpage by setting format=pdf.

Example Request

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&format=pdf&api_key=YOUR_KEY"

PDF Response

{
  "success": true,
  "data": {
    "pdf_url": "https://r2.shotapi.dev/screenshots/abc123.pdf",
    "page_count": 3,
    "format": "pdf",
    "file_size": 156789
  },
  "usage": {
    "credits_used": 44,
    "credits_limit": 500,
    "credits_remaining": 456
  }
}

Device Presets

Use device presets to emulate common device viewports and user agents automatically.

Preset	Width	Height	Scale	Mobile
`desktop`	1920	1080	1x	No
`laptop`	1366	768	1x	No
`tablet`	768	1024	2x	Yes
`tablet-landscape`	1024	768	2x	Yes
`mobile`	375	812	3x	Yes
`mobile-landscape`	812	375	3x	Yes
`iphone-14`	390	844	3x	Yes
`iphone-14-pro-max`	430	932	3x	Yes
`ipad-pro`	1024	1366	2x	Yes
`pixel-7`	412	915	2.625x	Yes

Example: Mobile Screenshot

curl "https://shotapi.dev/api/v1/screenshot?url=https://example.com&device=iphone-14&api_key=YOUR_KEY"

Error Codes

Code	Status	Description
`MISSING_API_KEY`	401	No API key provided
`INVALID_API_KEY`	401	API key is invalid or revoked
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`CREDITS_EXHAUSTED`	402	Monthly credit limit reached
`PREMIUM_REQUIRED`	403	Feature requires paid plan
`INVALID_URL`	400	URL is invalid or not accessible
`VALIDATION_ERROR`	400	Invalid parameter value
`SCREENSHOT_FAILED`	500	Failed to capture screenshot

Rate Limits

Plan	Requests/min	Screenshots/month	Premium Features
Free	10	500	No
Starter	60	2,500	Yes
Pro	120	10,000	Yes
Business	300	50,000	Yes

Ready to get started? Create a free account or upgrade your plan to unlock premium features.

API Documentation

Contents

Node.js SDK

Installation

Quick Start

SDK Features

Configuration

Error Handling

Authentication

Screenshot Endpoint

Basic Parameters

Example Request (GET)

Example Request (POST)

Example Response

Premium Features

Example: Capture Specific Element

Example: Custom CSS Injection

Example: Generate Thumbnail

PDF Generation

Example Request

PDF Response

Device Presets

Example: Mobile Screenshot

Error Codes

Rate Limits