Docs

Go SDK

The official Go SDK for the Screenshot Scout screenshot API. It is published as the Go module github.com/screenshotscout/screenshotscout-go, documented on pkg.go.dev, and developed in the screenshotscout-go repository.

Installation

Add the module to your project:

go get github.com/screenshotscout/screenshotscout-go

The SDK requires Go 1.25 or newer.

Get your API credentials

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. The SDK never reads credentials from environment variables on its own; your application supplies them explicitly.

Capture a screenshot

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

package main

import (
	"context"
	"log"
	"os"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient("YOUR_ACCESS_KEY", nil)
	if err != nil {
		log.Fatal(err)
	}

	fullPage := true
	response, err := client.Capture(
		context.Background(),
		"https://example.com",
		&screenshotscout.CaptureOptions{FullPage: &fullPage},
	)
	if err != nil {
		log.Fatal(err)
	}
	if response.Binary == nil {
		log.Fatal("Screenshot Scout returned a non-binary response")
	}
	if err := os.WriteFile("screenshot.png", response.Binary.Bytes, 0o600); err != nil {
		log.Fatal(err)
	}
}

Capture sends a POST request by default. The ResponseType option on CaptureOptions selects the response format. When you leave it unset, or set it to CaptureResponseTypeBinary, you get a binary response in response.Binary: the image data is in Bytes, and the exact screenshot URL is in ScreenshotURL when available.

Request a JSON result

Set ResponseType to CaptureResponseTypeJSON to receive a JSON object with the screenshot URL instead of the image bytes:

package main

import (
	"context"
	"fmt"
	"log"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient("YOUR_ACCESS_KEY", nil)
	if err != nil {
		log.Fatal(err)
	}

	responseType := screenshotscout.CaptureResponseTypeJSON
	response, err := client.Capture(
		context.Background(),
		"https://example.com",
		&screenshotscout.CaptureOptions{ResponseType: &responseType},
	)
	if err != nil {
		log.Fatal(err)
	}
	if response.JSON == nil {
		log.Fatal("Screenshot Scout returned a non-JSON response")
	}
	if response.JSON.Result.ScreenshotURL != nil {
		fmt.Println(*response.JSON.Result.ScreenshotURL)
	}
}

The parsed JSON body is in response.JSON.Result. Exactly one of response.Binary and response.JSON is non-nil; CaptureResponse.Kind tells you which one.

Set capture options

CaptureOptions provides every option in the screenshot option reference through PascalCase fields: full_page becomes FullPage, block_cookie_banners becomes BlockCookieBanners, and so on. Scalar fields are pointers: nil omits an option, while pointers to "", false, or zero send those values exactly. Options with a fixed set of documented values have constants, such as CaptureFormatWEBP and CaptureResponseTypeJSON. For a value the constants do not cover yet, use an explicit conversion, for example screenshotscout.CaptureFormat("future-format").

Build a capture URL

BuildCaptureURL creates a capture URL without making an API request, for cases where another application or an HTML <img> element loads the screenshot directly:

package main

import (
	"fmt"
	"log"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient("YOUR_ACCESS_KEY", nil)
	if err != nil {
		log.Fatal(err)
	}

	fullPage := true
	blockAds := true
	captureURL, err := client.BuildCaptureURL(
		"https://example.com",
		&screenshotscout.CaptureOptions{
			FullPage: &fullPage,
			BlockAds: &blockAds,
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(captureURL)
}

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 through ClientOptions:

package main

import (
	"log"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient(
		"YOUR_ACCESS_KEY",
		&screenshotscout.ClientOptions{SecretKey: "YOUR_SECRET_KEY"},
	)
	if err != nil {
		log.Fatal(err)
	}
	_ = client
}

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 returns an *APIError, with the HTTP status in StatusCode and the machine-readable error code and descriptive message in ErrorCode and ErrorMessage. Check for it with errors.As; the five error categories also have errors.Is sentinels, and failed requests are not retried automatically. The repository README documents all error types.

Full reference

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

On this page

InstallationGet your API credentialsCapture a screenshotRequest a JSON resultSet capture optionsBuild a capture URLSigned requestsErrorsFull reference