Ruby SDK

The official Ruby SDK for the Screenshot Scout screenshot API. It is distributed on RubyGems as screenshotscout and developed in the screenshotscout-ruby repository.

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page, copy the access key and secret key, and store them in a safe place.

Capture a screenshot

Create a client with your access key and call capture with the URL of the page you would like to take a screenshot of:

require "screenshotscout"

client = ScreenshotScout::Client.new(access_key: "YOUR_ACCESS_KEY")

response = client.capture(
  "https://example.com",
  ScreenshotScout::CaptureOptions.new(full_page: true)
)

File.binwrite("screenshot.png", response.bytes)
puts response.screenshot_url

capture sends a POST request by default. The response_type option on CaptureOptions selects the response format. When you leave it unset, or set it to CaptureResponseType::BINARY, the call returns a BinaryCaptureResponse: the image data is in bytes, and the exact screenshot URL is in screenshot_url when available.

Request a JSON result

Set response_type to CaptureResponseType::JSON to receive a JSON object with the screenshot URL instead of the image bytes:

require "screenshotscout"

client = ScreenshotScout::Client.new(access_key: "YOUR_ACCESS_KEY")

options = ScreenshotScout::CaptureOptions.new(
  response_type: ScreenshotScout::CaptureResponseType::JSON
)
response = client.capture("https://example.com", options)

puts response.result.screenshot_url

The parsed JSON body is in result.

Set capture options

CaptureOptions.new accepts every option in the screenshot option reference, with the same snake_case names: full_page, block_cookie_banners, and so on. Options with a fixed set of documented values have constants, such as CaptureFormat::WEBP and CaptureWaitUntil::LOAD; plain strings are also accepted. Repeated options such as cookies, headers, and the selector options accept arrays of strings.

Build a capture URL

Use build_capture_url when a browser, an HTML <img> element, or another application needs to load the screenshot directly. It creates the URL without making an API request:

require "screenshotscout"

client = ScreenshotScout::Client.new(access_key: "YOUR_ACCESS_KEY")

options = ScreenshotScout::CaptureOptions.new(full_page: true, block_ads: true)
capture_url = client.build_capture_url("https://example.com", options)
puts capture_url

The generated URL contains the access key. When a secret key is configured (see Signed requests), the SDK signs the URL automatically; otherwise it is unsigned. Treat generated URLs as sensitive. Before exposing one to browsers or users, configure a secret key and enable Require signed requests on the API Keys page.

Signed requests

Pass the API key's secret key as the secret_key argument when creating the client:

require "screenshotscout"

client = ScreenshotScout::Client.new(
  access_key: "YOUR_ACCESS_KEY",
  secret_key: "YOUR_SECRET_KEY"
)

The secret is used locally and is never transmitted. The client signs capture requests and generated capture URLs automatically. See the signed requests guide for details.

Errors

When the API returns a non-2xx response, the SDK raises ScreenshotScout::APIError, with the machine-readable error code in error_code and the descriptive message in error_message. All SDK exceptions inherit from ScreenshotScout::Error, so one rescue can handle any SDK error. The repository README documents all error classes.

Full reference

This page covers installation and your first captures. For everything else, see:

The repository README: GET requests, HTTP timeouts and a custom transport, raw responses, and all error classes.
The standalone examples in the repository.
The screenshot option reference: service behavior and allowed values for every option.