Skip to main content

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​

ParameterTypeDescription
urlstringURL input mode: webpage URL to capture
htmlstringHTML input mode: inline HTML markup to render and capture
apiKeystringYour API key (can also be passed in X-API-Key header)

Provide exactly one of url or html per request.

Optional Parameters​

Format & Output​

ParameterTypeDefaultDescription
formatstring"png"Output format: png, webp, jpeg, or pdf
pdfPageLayoutstring"paginated"PDF only. paginated — standard multi-page A4 print; single — one continuous page matching document/viewport size (closer to full-page PNG). Ignored when format is not pdf.
returnFilebooleantrueIf true, returns binary file; if false, returns JSON with base64 data
imageQualitynumber90Image quality (1-100) for JPEJ/WebP
scaleFactornumber1.0Scale factor (0.1-3.0) for image resolution

PDF capture (automatic): For format=pdf, the API always sets fullPage=true, fullPageScroll=true, and fullPageScrollDuration=1000 before rendering. You do not need to pass fullPage, fullPageScroll, or fullPageScrollDuration; any values you send for those parameters are overridden for PDF output.

Viewport & Device​

ParameterTypeDefaultDescription
devicestring"desktop"Device preset ID or category. See Device Presets for all options
viewportWidthnumber1920Viewport width in pixels
viewportHeightnumber1080Viewport height in pixels
themestring"auto"Theme: light, dark, or auto

Page Capture​

ParameterTypeDefaultDescription
fullPagebooleanfalseCapture entire page including content below fold. Ignored when format is pdf — PDF always uses full-page capture.
fullPageScrollbooleanfalseEnable enhanced scrolling for lazy-loaded content. Ignored when format is pdf — always enabled for PDF.
fullPageScrollDurationnumber1000Scroll duration in milliseconds (enhanced scroll). Ignored when format is pdf — fixed at 1000 ms for PDF.
clipSelectorstringnullCSS selector to capture only specific element

Timing & Waiting​

ParameterTypeDefaultDescription
delaynumber0Delay in milliseconds before taking screenshot
waitUntilstring"load"Wait condition: load, domcontentloaded, networkidle0, networkidle2
waitForSelectorstringnullCSS selector to wait for before screenshot

Content Filtering​

ParameterTypeDefaultDescription
removeAdsbooleanfalseAutomatically remove ads
removeCookieBannersbooleanfalseAutomatically remove cookie consent banners
removeSelectorsstringnullComma-separated CSS selectors to remove
blockResourcesstring""Comma-separated resource types to block: stylesheet, script, image, font, media
blockUrlsstring""Comma-separated URLs or patterns to block (supports wildcards)

Custom Request​

ParameterTypeDefaultDescription
userAgentstringnullCustom user agent string. Overrides the device preset's default user agent when provided
headersJSON stringnullCustom HTTP headers as a JSON object (e.g., {"Authorization":"Bearer token"}). Max 20 headers

OpenAI Analysis (Optional)​

ParameterTypeDefaultDescription
openaiPromptstringnullPrompt used to analyze the generated screenshot image
openaiApiKeystringnullYour OpenAI API key (fallback option). Prefer X-OpenAI-Api-Key header for better security

When using OpenAI analysis:

  • Provide both openaiPrompt and an OpenAI key.
  • Recommended key transport: X-OpenAI-Api-Key header.
  • openaiApiKey query parameter fallback is supported for compatibility.
  • We do not store your OpenAI API key in our database.

Geolocation​

ParameterTypeDefaultDescription
latitudenumbernullGPS latitude (-90 to 90). Must be provided together with longitude
longitudenumbernullGPS longitude (-180 to 180). Must be provided together with latitude

Proxy & Network​

ParameterTypeDefaultDescription
proxyUrlstringnullProxy URL (e.g., http://proxy.example.com:8080)
proxyUsernamestringnullProxy username (if required)
proxyPasswordstringnullProxy password (if required)

Caching​

ParameterTypeDefaultDescription
cacheEnabledbooleanfalseEnable response caching
cacheTtlnumber3600Cache TTL in seconds

Storage (Per-Request)​

ParameterTypeDefaultDescription
requestStorageEnabledbooleanfalseUse per-request storage configuration
requestStorageEndpointstringnullS3-compatible endpoint URL
requestStorageAccessKeyIdstringnullStorage access key ID
requestStorageSecretAccessKeystringnullStorage secret access key
requestStorageBucketstringnullStorage bucket name
requestStorageRegionstring"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>
X-BoltShot-AI-Result: <analysis text when openaiPrompt is provided>
X-BoltShot-AI-Result-Truncated: true|false

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...",
    "aiResult": {
      "text": "The screenshot shows a product listing page with 24 items and a visible filter sidebar.",
      "model": "gpt-4.1-mini"
    }
  }
}

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)
  • aiResult: OpenAI analysis output when openaiPrompt is provided

Examples​

Basic Screenshot​

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

Inline HTML Screenshot​

GET https://api.boltshot.dev/capture?html=%3Chtml%3E%3Cbody%3E%3Ch1%3EHello%20BoltShot%3C%2Fh1%3E%3C%2Fbody%3E%3C%2Fhtml%3E&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 (iPhone 16)​

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

Mobile Screenshot (Samsung Galaxy S24)​

GET https://api.boltshot.dev/capture?url=https://example.com&device=samsung-galaxy-s24&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​

Paginated (default — normal multi-page PDF):

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

(pdfPageLayout can be omitted — it defaults to paginated.)

Single long page (closer to a full-page PNG — one continuous page):

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

PDFs use Chromium’s print pipeline (not the same as raster screenshots).

  • Full page + scroll is applied automatically for every PDF (fullPage, fullPageScroll, and fullPageScrollDuration are set server-side; see PDF capture (automatic) under optional parameters).
  • pdfPageLayout=paginated (default): A4 pages with margins — typical multi-page PDF.
  • pdfPageLayout=single: one PDF page sized to the full document height (full-page capture is automatic) or viewport height for non–full-page requests. Very large pages may fall back to paginated A4 (engine limits).

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

Geolocation (Location-Specific Content)​

GET https://api.boltshot.dev/capture?url=https://example.com/store-locator&latitude=40.7128&longitude=-74.0060&apiKey=your_api_key_here

This emulates GPS coordinates for New York City, useful for capturing location-aware content like maps, store locators, or "near me" search results.

Custom User Agent​

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

Screenshot with Custom Headers (Authenticated Page)​

GET https://api.boltshot.dev/capture?url=https://example.com/dashboard&headers=%7B%22Authorization%22%3A%22Bearer%20eyJhbG...%22%2C%22Accept-Language%22%3A%22fr-FR%22%7D&apiKey=your_api_key_here

The headers parameter accepts a URL-encoded JSON object. The decoded value is:

{"Authorization":"Bearer eyJhbG...","Accept-Language":"fr-FR"}

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.

For HTML mode, always URL-encode the html value and keep it reasonably small. GET query strings have practical size limits across browsers/proxies; use compact markup and avoid very large inline assets.

Device Presets​

You can pass a specific device ID or a legacy category name (desktop, mobile, tablet) to the device parameter. When using a specific device, the viewport, scale factor, and user agent are all set automatically.

Desktop​

Device IDNameViewportScale
desktop-1080pDesktop 1080p1920×10801x
desktop-1440pDesktop 1440p2560×14401x

iPhone​

Device IDNameViewportScale
iphone-seiPhone SE375×6672x
iphone-14iPhone 14390×8443x
iphone-14-plusiPhone 14 Plus428×9263x
iphone-14-pro-maxiPhone 14 Pro Max430×9323x
iphone-15iPhone 15393×8523x
iphone-15-pro-maxiPhone 15 Pro Max430×9323x
iphone-16iPhone 16393×8523x
iphone-16-pro-maxiPhone 16 Pro Max440×9563x

Samsung​

Device IDNameViewportScale
samsung-galaxy-s24Galaxy S24360×7803x
samsung-galaxy-s24-ultraGalaxy S24 Ultra384×8243.75x
samsung-galaxy-a54Galaxy A54360×8002.625x
samsung-galaxy-z-fold5Galaxy Z Fold 5373×8413x

Google Pixel​

Device IDNameViewportScale
google-pixel-8Pixel 8412×9152.625x
google-pixel-8-proPixel 8 Pro412×9153.5x

iPad​

Device IDNameViewportScale
ipad-miniiPad Mini768×10242x
ipad-airiPad Air820×11802x
ipad-pro-11iPad Pro 11"834×11942x
ipad-pro-12.9iPad Pro 12.9"1024×13662x

Other Tablets​

Device IDNameViewportScale
samsung-galaxy-tab-s9Galaxy Tab S9800×12802x
surface-proSurface Pro912×13682x

Legacy Category Names​

For backward compatibility, you can still use desktop, mobile, or tablet as shorthand:

CategoryMaps to
desktopdesktop-1080p
mobileiphone-15
tabletipad-air
tip

You can still override viewportWidth and viewportHeight when using a device preset if you need a custom resolution.

Geolocation Emulation​

The latitude and longitude parameters let you emulate the browser's GPS coordinates. Websites that use the JavaScript Geolocation API (navigator.geolocation.getCurrentPosition()) will receive the coordinates you specify.

Common use cases:

  • Capturing location-specific map views
  • Screenshotting store locator pages with nearby results
  • Testing geo-targeted landing pages

Both parameters are required together — providing only one will return a validation error.

note

This is browser-level geolocation emulation (GPS spoofing), not network-level geo-routing. It affects JavaScript-based location detection, not IP-based detection. For IP-based geo-targeting, combine geolocation with the proxyUrl parameter using a geo-targeted proxy.

Custom Headers & User Agent​

User Agent​

By default, the user agent is determined by the selected device preset (e.g., selecting iphone-16 sends an iPhone 16 Safari user agent). You can override this with the userAgent parameter.

HTTP Headers​

Custom HTTP headers allow you to capture screenshots of:

  • Authenticated pages using Authorization or Cookie headers
  • Localized content using Accept-Language
  • Pages behind token gating using custom headers

Pass headers as a JSON object via the headers parameter:

headers={"Authorization":"Bearer token","Cookie":"session=abc123"}
caution

The following headers are blocked for security reasons: Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer, Proxy-Authorization, Proxy-Connection.

warning

Custom headers are not stored in the database for security. Only the userAgent is saved for logging purposes.

Best Practices​

Performance​

  1. 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

  2. Optimize image quality

    • Use imageQuality=80-90 for most cases
    • Use scaleFactor=1.0 unless you need higher resolution

  3. Enable caching

    • Set cacheEnabled=true for repeated screenshots
    • Adjust cacheTtl based on content update frequency

Reliability​

  1. Use delays for dynamic content

    • Add delay parameter for JavaScript-rendered content
    • Use waitForSelector for specific elements

  2. Handle errors gracefully

    • Check response status codes
    • Implement retry logic for transient failures

  3. 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

  • 403 Forbidden:

    • TARGET_PROTECTED - Target page is behind anti-bot verification (CAPTCHA/challenge)

  • 429 Too Many Requests:

    • RATE_LIMIT_EXCEEDED - Rate limit exceeded

  • 500 Internal Server Error:

    • INTERNAL_ERROR - Internal server error
    • OPERATION_FAILED - Operation failed

Protected Targets (CAPTCHA/Challenge Pages)​

If the requested URL resolves to an anti-bot verification interstitial (for example reCAPTCHA, hCaptcha, or Cloudflare challenge pages), the API fails fast with:

  • HTTP status: 403
  • Error code: TARGET_PROTECTED
  • Behavior: No screenshot is returned, and credits are consumed only on successful captures

Example Error Response​

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

Next Steps​