Screenshot API

The Screenshot API is the core of BoltShot. It allows you to capture high-quality screenshots of any website with extensive customization options.

Endpoint

GET /capture

The screenshot API uses GET requests with query parameters for all options.

Authentication

Pass your API key as a query parameter:

GET https://api.boltshot.dev/capture?url=https://example.com&apiKey=your_api_key_here

You can also pass the API key in the X-API-Key header as an alternative. See Authentication for details.

Basic Usage

Simple Request

GET https://api.boltshot.dev/capture?url=https://example.com&apiKey=your_api_key_here

Request Parameters

Required Parameters

Parameter	Type	Description
`url`	string	The URL of the webpage to screenshot
`apiKey`	string	Your API key (can also be passed in `X-API-Key` header)

Optional Parameters

Format & Output

Parameter	Type	Default	Description
`format`	string	`"png"`	Output format: `png`, `webp`, or `pdf`
`returnFile`	boolean	`true`	If `true`, returns binary file; if `false`, returns JSON with base64 data
`imageQuality`	number	`90`	Image quality (1-100) for JPEJ/WebP
`scaleFactor`	number	`1.0`	Scale factor (0.1-3.0) for image resolution

Viewport & Device

Parameter	Type	Default	Description
`device`	string	`"desktop"`	Device type: `desktop`, `mobile`, or `tablet`
`viewportWidth`	number	`1920`	Viewport width in pixels
`viewportHeight`	number	`1080`	Viewport height in pixels
`theme`	string	`"auto"`	Theme: `light`, `dark`, or `auto`

Page Capture

Parameter	Type	Default	Description
`fullPage`	boolean	`false`	Capture entire page including content below fold
`fullPageScroll`	boolean	`false`	Enable enhanced scrolling for lazy-loaded content
`fullPageScrollDuration`	number	`1000`	Scroll duration in milliseconds
`clipSelector`	string	`null`	CSS selector to capture only specific element

Timing & Waiting

Parameter	Type	Default	Description
`delay`	number	`0`	Delay in milliseconds before taking screenshot
`waitUntil`	string	`"load"`	Wait condition: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`
`waitForSelector`	string	`null`	CSS selector to wait for before screenshot

Content Filtering

Parameter	Type	Default	Description
`removeAds`	boolean	`false`	Automatically remove ads
`removeCookieBanners`	boolean	`false`	Automatically remove cookie consent banners
`removeSelectors`	string	`null`	Comma-separated CSS selectors to remove
`blockResources`	string	`""`	Comma-separated resource types to block: `stylesheet`, `script`, `image`, `font`, `media`
`blockUrls`	string	`""`	Comma-separated URLs or patterns to block (supports wildcards)

Proxy & Network

Parameter	Type	Default	Description
`proxyUrl`	string	`null`	Proxy URL (e.g., `http://proxy.example.com:8080`)
`proxyUsername`	string	`null`	Proxy username (if required)
`proxyPassword`	string	`null`	Proxy password (if required)

Caching

Parameter	Type	Default	Description
`cacheEnabled`	boolean	`false`	Enable response caching
`cacheTtl`	number	`3600`	Cache TTL in seconds

Storage (Per-Request)

Parameter	Type	Default	Description
`requestStorageEnabled`	boolean	`false`	Use per-request storage configuration
`requestStorageEndpoint`	string	`null`	S3-compatible endpoint URL
`requestStorageAccessKeyId`	string	`null`	Storage access key ID
`requestStorageSecretAccessKey`	string	`null`	Storage secret access key
`requestStorageBucket`	string	`null`	Storage bucket name
`requestStorageRegion`	string	`"us-east-1"`	Storage region

Response Format

Binary Response (returnFile: true)

When returnFile=true (default), the API returns the screenshot as a binary file:

Headers:

Content-Type: image/png (or image/webp or application/pdf)
Content-Disposition: inline; filename="screenshot.png"
Content-Length: <file_size>

Body: Binary file data

JSON Response (returnFile: false)

When returnFile=false, the API returns JSON in standardized format:

{
  "success": true,
  "data": {
    "requestId": "uuid",
    "fileName": "screenshot.png",
    "processingTime": 2500,
    "fileSize": 1024000,
    "url": "https://storage.example.com/screenshots/screenshot.png",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANS..."
  }
}

Response Fields:

success: Always true for successful requests
data: Object containing the screenshot information

Data Fields:

requestId: Unique identifier for this request
fileName: Generated filename
processingTime: Time taken in milliseconds
fileSize: File size in bytes
url: Storage URL (if storage is configured)
imageData: Base64-encoded image (for PNG/WebP, not PDF)

Examples

Basic Screenshot

GET https://api.boltshot.dev/capture?url=https://example.com&apiKey=your_api_key_here

Full-Page Screenshot

GET https://api.boltshot.dev/capture?url=https://example.com&fullPage=true&format=png&apiKey=your_api_key_here

Mobile Screenshot

GET https://api.boltshot.dev/capture?url=https://example.com&device=mobile&viewportWidth=375&viewportHeight=667&apiKey=your_api_key_here

Capture Specific Element

GET https://api.boltshot.dev/capture?url=https://example.com&clipSelector=%23main-content&format=png&apiKey=your_api_key_here

Note: URL-encode special characters in selectors (e.g., # becomes %23)

GET https://api.boltshot.dev/capture?url=https://example.com&removeAds=true&removeCookieBanners=true&fullPage=true&apiKey=your_api_key_here

Block Resources

GET https://api.boltshot.dev/capture?url=https://example.com&blockResources=stylesheet,script&format=png&apiKey=your_api_key_here

Wait for Element

GET https://api.boltshot.dev/capture?url=https://example.com&waitForSelector=.content-loaded&delay=2000&waitUntil=networkidle0&apiKey=your_api_key_here

Generate PDF

GET https://api.boltshot.dev/capture?url=https://example.com&format=pdf&fullPage=true&apiKey=your_api_key_here

High-Quality Screenshot

GET https://api.boltshot.dev/capture?url=https://example.com&format=png&imageQuality=100&scaleFactor=2.0&viewportWidth=3840&viewportHeight=2160&apiKey=your_api_key_here

Dark Mode Screenshot

GET https://api.boltshot.dev/capture?url=https://example.com&theme=dark&fullPage=true&apiKey=your_api_key_here

With Proxy

GET https://api.boltshot.dev/capture?url=https://example.com&proxyUrl=http://proxy.example.com:8080&proxyUsername=user&proxyPassword=pass&apiKey=your_api_key_here

JSON Response with Preview

GET https://api.boltshot.dev/capture?url=https://example.com&returnFile=false&format=png&apiKey=your_api_key_here

URL Encoding

When using query parameters, make sure to URL-encode special characters:

# → %23
& → %26
= → %3D
(space) → %20 or +
, → %2C

Most HTTP clients (like cURL) handle this automatically, but be aware when constructing URLs manually.

Device Presets

Desktop

Viewport: 1920x1080
User Agent: Desktop Chrome

Mobile

Viewport: 375x667 (iPhone)
User Agent: Mobile Safari

Tablet

Viewport: 768x1024 (iPad)
User Agent: Tablet Safari

Best Practices

Performance

Use appropriate wait conditions
- load: Fastest, waits for page load
- networkidle0: Waits for all network activity to stop
- networkidle2: Waits for max 2 network connections
Optimize image quality
- Use imageQuality=80-90 for most cases
- Use scaleFactor=1.0 unless you need higher resolution
Enable caching
- Set cacheEnabled=true for repeated screenshots
- Adjust cacheTtl based on content update frequency

Reliability

Use delays for dynamic content
- Add delay parameter for JavaScript-rendered content
- Use waitForSelector for specific elements
Handle errors gracefully
- Check response status codes
- Implement retry logic for transient failures
Monitor usage
- Track request IDs for debugging
- Monitor processing times

Error Handling

See Errors for detailed error codes and handling.

Error Response Format

All errors follow this standardized format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details (optional)"
  }
}

Common Error Codes

400 Bad Request:
- VALIDATION_ERROR - Validation failed
- MISSING_REQUIRED_FIELD - Required field missing
- INVALID_INPUT - Invalid input provided
401 Unauthorized:
- API_KEY_REQUIRED - API key is required
- INVALID_API_KEY - Invalid API key
- API_KEY_EXPIRED - API key has expired
402 Payment Required:
- INSUFFICIENT_CREDITS - Insufficient credits
429 Too Many Requests:
- RATE_LIMIT_EXCEEDED - Rate limit exceeded
500 Internal Server Error:
- INTERNAL_ERROR - Internal server error
- OPERATION_FAILED - Operation failed

Example Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "viewportWidth",
        "message": "Must be a number",
        "value": "invalid"
      }
    ]
  }
}

Next Steps

Review API Reference for endpoint details
Learn about Authentication methods
Check out Integrations for automation tools

Endpoint​

Authentication​

Basic Usage​

Simple Request​

Request Parameters​

Required Parameters​

Optional Parameters​

Format & Output​

Viewport & Device​

Page Capture​

Timing & Waiting​

Content Filtering​

Proxy & Network​

Caching​

Storage (Per-Request)​

Response Format​

Binary Response (returnFile: true)​

JSON Response (returnFile: false)​

Examples​

Basic Screenshot​

Full-Page Screenshot​

Mobile Screenshot​

Capture Specific Element​

Remove Ads and Cookie Banners​

Block Resources​

Wait for Element​

Generate PDF​

High-Quality Screenshot​

Dark Mode Screenshot​

With Proxy​

JSON Response with Preview​

URL Encoding​

Device Presets​

Desktop​

Mobile​

Tablet​

Best Practices​

Performance​

Reliability​

Error Handling​

Error Response Format​

Common Error Codes​

Example Error Response​

Next Steps​