About

Screengrabber is a self-hosted REST API service that uses Microsoft Edge via Playwright to capture screenshots of web pages. It supports configurable viewport sizes, aspect ratios, zoom levels, output formats, and Redis-backed caching.

Quick Start

Make a GET request with the target URL as the first path segment. All other path segments are optional and control the screenshot appearance.

GET /{url}/{size}/{aspectRatio}/{zoom}/_modifiers?format=jpeg HTTP/1.1
X-Api-Key: your-api-key

For example, to capture a 1024×1024 screenshot of https://example.com:

https://screengrabber.example.com/https%3A%2F%2Fexample.com/large

Authentication

If API_KEYS is configured, every request must include an X-Api-Key header. The service returns 401 Unauthorized for missing or invalid keys.

X-Api-Key: your-api-key

If API_KEYS is empty (the default), no authentication is required.

Self-Hosting

Screengrabber ships as a Docker image and supports three deployment modes.

• standalone with a bundled Caddy reverse proxy,
• proxied behind an existing Dockerised reverse proxy, or
• proxied behind a host-level proxy such as Nginx or Apache. See Deployment for full setup instructions.

Docker Quick Start (single container)

If you already have Redis and only want to run the API container directly:

docker run -d --name screengrabber-api \
	-p 8080:8080 \
	-e REDIS_CONNECTION=host.docker.internal:6379 \
	-e SCREENSHOT_CACHE_TTL_HOURS=24 \
	-e SCREENSHOT_CONCURRENCY=4 \
	-e API_KEYS=your-key-here \
	homotechsual/screengrabber:latest

Use Docker Compose for production setups and when running bundled Redis.