ScreenShot This! - API Manual

Welcome to ScreenShot This! API. This API allows you to take screenshots and PDFs of webpages, record short videos, capture console logs, block ads, and more. Below you’ll find everything you need to get started, including authentication instructions, available parameters, sample requests, and example responses.

1. Introduction & Overview
2. Authentication
3. Request Parameters
4. Example Requests
5. Response Format
6. Error Handling
7. Conclusion

1. Introduction & Overview

The ScreenShot This! service exposes a single main endpoint for all screenshot operations:

POST /api/screenshot

By sending a JSON payload with the URL you want to capture, plus your desired options, you can retrieve the screenshot (or PDF) directly in the JSON response as a Base64 string, or as a hosted file link if the file is large.

Additionally, you can record a short video of the page loading, block ads, throttle network conditions (for testing slow connections), disable JavaScript, capture HAR files, generate traces, set geolocation, basic auth, custom headers/cookies, resize images, and more.

2. Authentication

All requests must include a valid API key. You can provide this API key in three possible ways:

Query parameter: ?access_key=YOUR_KEY
JSON body property: "access_key": "YOUR_KEY"
Request header: X-API-KEY: YOUR_KEY

For example, if your key is TEST12345, you can do any one of:

# Using a query parameter:
curl -X POST "https://screenshot-this.com/api/screenshot?access_key=TEST12345" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://example.com" }'

# Using the body param:
curl -X POST "https://screenshot-this.com/api/screenshot" \
     -H "Content-Type: application/json" \
     -d '{
       "access_key": "TEST12345",
       "url": "https://example.com"
     }'

# Using a header:
curl -X POST "https://screenshot-this.com/api/screenshot" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: TEST12345" \
     -d '{ "url": "https://example.com" }'

3. Request Parameters

Below is a list of parameters you can include in your JSON payload (or query parameters) when calling /api/screenshot:

Parameter	Type	Default	Description
`url`	string	none	Required. The URL to capture (e.g. `https://example.com`).
`response_type`	string	`"image"`	Set to `"image"` or `"pdf"`. Determines if you want an image screenshot or a PDF.
`record_video`	boolean	`false`	Whether to record a `.webm` video of the browser session.
`capture_console`	boolean	`false`	If `true`, captures console messages (logs, warnings, errors) from the page.
`capture_har`	boolean	`false`	If `true`, captures a HAR (HTTP Archive) of all network requests, returning `har_url` in the response.
`capture_trace`	boolean	`false`	If `true`, captures a Playwright trace (ZIP file), returning `trace_url` in the response.
`generate_debug_prompt`	boolean	`false`	If `true`, the API will generate an AI debug prompt and return its download link in the `debug_prompt_url` field. Requires that `capture_trace` also be `true` (the debug prompt is derived from trace data).
`iframe_selector`	string	none	CSS selector pointing to an `<iframe>` if you want a screenshot inside that iframe.
`disable_js`	boolean	`false`	If `true`, JavaScript is entirely disabled for the page.
`ad_block`	boolean	`false`	If `true`, attempts to block known ad domains and trackers (via manual host blocking + Ghostery).
`hide_ads`	boolean	`false`	If `true`, injects simple CSS to hide common ad elements on the page.
`device`	string	none	A built-in device preset (e.g. `"iPhone 12"` or `"desktop"`) for viewport and user-agent emulation.
`network_profile`	string	none	Throttles network. Possible values: `"slow"`, `"3g"`, or `"4g"`.
`offline`	boolean	`false`	If `true`, the browser is forced offline after initial load.
`wait_js_condition`	string	none	A JS expression to wait for (e.g. `"window.pageReady === true"`).
`wait_timeout`	integer	`10000`	Maximum time (ms) to wait for a selector or JS condition.
`wait_for_selector`	string	none	A CSS selector to wait for (e.g. `"#my-element"`).
`delay`	integer	`0`	A delay (ms) before taking the screenshot.
`wait_until`	string	none	Controls `page.goto` wait. Possible values: `"load"`, `"domcontentloaded"`, `"networkidle"`.
`image_format`	string	`"png"`	Image format for the screenshot. Supported values: `"png"` `"jpeg"` `"webp"` (requires a modern Chromium context with Playwright 1.21+)
`image_quality`	integer	none	Quality (1–100) for `"jpeg"` or `"webp"`. Ignored if `image_format` is `"png"`. Higher means better quality but larger file size.
`full_page`	boolean	`false`	If `true`, captures the entire scrollable page.
`max_image_width`	integer	none	Optionally resize the captured image to this maximum width (in px). Maintains aspect ratio.
`max_image_height`	integer	none	Optionally resize the captured image to this maximum height (in px). Maintains aspect ratio.
`custom_user_agent`	string	none	Overrides the User-Agent header, e.g. `"MyApp/1.2"`.
`viewport_width`	integer	none	Custom viewport width (px). Overrides any device preset.
`viewport_height`	integer	none	Custom viewport height (px). Overrides any device preset.
`device_scale_factor`	float	none	Pixel density scaling (e.g. `2` for "Retina").
`include_meta`	boolean	`false`	If `true`, includes URL and status code in the JSON response.
`ignore_https_errors`	boolean	`false`	If `true`, the browser will ignore invalid SSL certificates and proceed anyway.
`basic_auth_user`	string	none	Basic HTTP auth username for pages requiring HTTP Auth.
`basic_auth_pass`	string	none	Basic HTTP auth password for pages requiring HTTP Auth.
`geolocation`	object	none	Set the device geolocation with `{"latitude": 37.7749, "longitude": -122.4194}`, for example.
`locale`	string	none	Set the browser locale (e.g. `"en-US"`, `"fr-FR"`).
`headers`	object	none	Custom request headers, e.g. `{ "X-My-Header": "someValue", "Referer": "https://google.com" }`
`cookies`	array	none	An array of cookie objects to set before navigation, e.g. `[ { "name": "testCookie", "value": "abc123", "domain": "example.com" } ]`

4. Example Requests

Below are sample curl requests that illustrate how to use the parameters above. Adjust the domain/port in the URLs as needed, and replace TEST12345 with your own key.

4.1 Minimal Screenshot Request

Goal: Capture a simple PNG screenshot of https://example.com.

curl -X POST "https://screenshot-this.com/api/screenshot" \
     -H "Content-Type: application/json" \
     -d '{
       "access_key": "TEST12345",
       "url": "https://example.com"
     }'

4.2 Full-Page JPEG Screenshot

Goal: Capture the entire scrollable page in JPEG format, quality 80.

{
  "access_key": "TEST12345",
  "url": "https://www.wikipedia.org",
  "full_page": true,
  "image_format": "jpeg",
  "image_quality": 80
}

4.3 Full-Page WebP Screenshot

Goal: Capture a full-page screenshot in webp format, with a custom quality of 75.

{
  "access_key": "TEST12345",
  "url": "https://www.wikipedia.org",
  "full_page": true,
  "image_format": "webp",
  "image_quality": 75
}

4.4 PDF Output

Goal: Return a PDF of the page instead of an image. Include metadata as well.

{
  "access_key": "TEST12345",
  "url": "https://www.example.com",
  "response_type": "pdf",
  "include_meta": true
}

4.5 Recording a Video

Goal: Record a .webm video of the entire page load.

{
  "access_key": "TEST12345",
  "url": "https://news.ycombinator.com",
  "record_video": true
}

4.6 Using a Built-In Device Preset

Goal: Emulate an iPhone 12.

{
  "access_key": "TEST12345",
  "url": "https://m.example.com",
  "device": "iPhone 12"
}

4.7 Custom User-Agent & Viewport

Goal: Set a custom UA plus a 1920 x 1080 viewport.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "custom_user_agent": "MyCustomAgent/1.0",
  "viewport_width": 1920,
  "viewport_height": 1080
}

4.8 Waiting for a Selector

Goal: Do not capture the screenshot until an element with ID #my-dynamic-element appears.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "wait_for_selector": "#my-dynamic-element",
  "wait_timeout": 15000
}

4.9 Waiting for a JavaScript Condition

Goal: Wait until window.pageReady === true is true, up to 20 seconds.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "wait_js_condition": "window.pageReady === true",
  "wait_timeout": 20000
}

4.10 Delayed Capture

Goal: Wait 5 seconds after the page loads, then capture.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "delay": 5000
}

4.11 Ad Blocking

Goal: Block ads & trackers, and hide common ad elements.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "ad_block": true,
  "hide_ads": true
}

4.12 Disabling JavaScript

Goal: Render the page with no JavaScript.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "disable_js": true
}

4.13 Capturing Inside an Iframe

Goal: Capture the full content of a specified iframe, or fall back to capturing just the iframe’s bounding box.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "iframe_selector": "iframe#iframe-id"
}

4.14 Network Throttling

Goal: Emulate a 3G connection.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "network_profile": "3g"
}

4.15 Offline Mode

Goal: Go offline after the page loads.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "offline": true
}

4.16 Including Metadata

Goal: Return the final URL and HTTP status code in the JSON response.

{
  "access_key": "TEST12345",
  "url": "https://example.com/some/redirect",
  "include_meta": true
}

4.17 Capturing Console Logs

Goal: Capture all console messages in the JSON response.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "capture_console": true
}

4.18 Capturing a HAR File

Goal: Capture a HAR (HTTP Archive) of network traffic.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "capture_har": true
}

4.19 Capturing a Trace

Goal: Capture a full Playwright trace (screenshots, snapshots) for debugging.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "capture_trace": true
}

4.20 Ignoring HTTPS Errors

Goal: Proceed even if the SSL certificate is invalid.

{
  "access_key": "TEST12345",
  "url": "https://self-signed.badssl.com",
  "ignore_https_errors": true
}

4.21 Setting Basic Auth

Goal: Access a page protected by basic authentication.

{
  "access_key": "TEST12345",
  "url": "https://example.com/protected",
  "basic_auth_user": "myUser",
  "basic_auth_pass": "myPass"
}

4.22 Setting Geolocation & Locale

Goal: Pretend to be in San Francisco, US, with a US English locale.

{
  "access_key": "TEST12345",
  "url": "https://maps.example.com",
  "geolocation": { "latitude": 37.7749, "longitude": -122.4194 },
  "locale": "en-US"
}

4.23 Custom Headers & Cookies

Goal: Set extra HTTP headers and custom cookies before loading.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "headers": {
    "X-My-Header": "Value123",
    "Referer": "https://google.com"
  },
  "cookies": [
    { "name": "testCookie", "value": "abc123", "domain": "example.com" },
    { "name": "userId", "value": "999", "domain": "example.com" }
  ]
}

4.24 Resizing the Captured Image

Goal: Capture a screenshot but ensure its maximum size is 800×600.

{
  "access_key": "TEST12345",
  "url": "https://example.com",
  "max_image_width": 800,
  "max_image_height": 600
}

4.25 Generating an AI Debug Prompt

Goal: Capture a Playwright trace and generate an AI debug prompt.

{
    "access_key": "TEST12345",
    "url": "https://example.com/problem-page",
    "capture_trace": true,
    "generate_debug_prompt": true
}

In the response, you may see a debug_prompt_url field containing a downloadable text file with AI-generated debugging insights for your captured trace.

5. Response Format

Regardless of whether you request an image or a PDF, the service returns a JSON object. Depending on your options and file sizes, you can see some of the following fields:

image (Base64-encoded screenshot)
image_url (URL to screenshot, if too large for inline Base64)
pdf (Base64-encoded PDF)
pdf_url (URL to PDF, if too large for inline Base64)
video_url (URL to a recorded .webm video, if record_video=true)
console (Array of console messages, if capture_console=true)
url, status (If include_meta=true)
image_format (Echoes back the format used, e.g. "webp")
har_url (If capture_har=true)
trace_url (If capture_trace=true)
debug_prompt_url (If generate_debug_prompt=true)

{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAA...",
  "image_format": "png",
  "console": [
    {
      "type": "log",
      "text": "Page loaded successfully",
      "location": {}
    },
    {
      "type": "error",
      "text": "Uncaught ReferenceError: something is not defined",
      "location": { "url": "https://example.com/script.js", "lineNumber": 42 }
    }
  ],
  "url": "https://example.com/final-redirect",
  "status": 200,
  "har_url": "https://screenshot-this.com/static/har_1629871234.har",
  "trace_url": "https://screenshot-this.com/static/trace_1629871234.zip"
}

6. Error Handling

In case of errors (e.g., invalid URL, navigation problems, internal errors), the service returns an HTTP 500 status code with a JSON body:

{
  "error": "Screenshot failed",
  "details": "Some descriptive error message"
}

If you do not supply a valid API key, you will receive 401 Unauthorized with an error message:

{
  "error": "API key missing"
}
{
  "error": "Invalid API key"
}

7. Conclusion

That’s it! You now have a comprehensive overview of the ScreenShot This! API. By combining the url parameter with the other options, you can capture nearly any webpage scenario—from simple PNG screenshots to advanced offline or ad-blocked testing with recorded videos, PDF generation, console logs, HAR captures, detailed Playwright traces, basic auth, geolocation, custom headers/cookies, and more.

New in this version:

Support for "webp" image format (requires a modern Chromium context).
Adjustable image_quality for "jpeg" or "webp" (range 1–100).
HAR capture (capture_har) and Playwright trace capture (capture_trace).
Ability to ignore HTTPS errors (ignore_https_errors).
Basic Auth support (basic_auth_user/basic_auth_pass).
Geolocation (geolocation) and locale (locale).
Custom headers (headers) and cookies (cookies).
Image resizing (max_image_width/max_image_height).
AI Debug Prompt generation (generate_debug_prompt), leveraging trace data for deeper insights.

Enjoy your automated screenshotting, and explore the variety of options to best suit your project needs!

ScreenShot This! – API Manual