Shots Developer Portal

Shots is an open-source screenshot editor and workspace platform with editor utility endpoints and a tenant REST API, both authenticated by a signed-in session or a workspace API key. Scalar provides an interactive reference, the contract is published as OpenAPI 3.1, and the application is open source under Apache 2.0.

Start here

Interactive API reference

Explore every REST operation, copy examples, and send requests through Scalar.

API guides

Authentication, rate limits, request and response examples, and the error-code table.

OpenAPI 3.1 specification

Machine-readable contract with operationIds, typed parameters, and response schemas.

Authentication and rate limits

Workspace API keys, signed-in sessions, and rate limits for every endpoint.

AI agents (MCP)

Connect Claude, ChatGPT, Cursor, and other agents to a workspace through the Shots MCP server.

llms.txt

Markdown site overview for AI agents and LLM crawlers.

llms-full.txt

Long-form Markdown reference covering features and the API.

API keys

Create a workspace API key in Settings → Developer API (/workspace/developers). Utility endpoints such as /api/screenshot accept a key with the artifact:read scope in X-API-Key or a signed-in session, and per-IP limits apply on top. Workspace-scoped /api/v1 operations require a key with the declared scope or an authorized signed-in session. Details are in authentication and rate limits.

Quickstart

1. Capture a live page

This utility accepts a URL and returns a base64 PNG. Send a workspace API key in X-API-Key.

curl -s -X POST https://shots.playbookmedia.io/api/screenshot \
  -H "X-API-Key: $SHOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","deviceType":"desktop"}' \
  | jq -r .screenshot | base64 -d > shot.png

2. Optimize the export

Send the image back through Sharp to recompress it as WebP.

curl -s -X POST https://shots.playbookmedia.io/api/export \
  -H "X-API-Key: $SHOTS_API_KEY" \
  -F "[email protected]" \
  -F "format=webp" \
  -F "qualityPreset=high" \
  -o shot.webp

3. Handle failures

Every failing request returns the same JSON envelope. Branch on code.

{
  "error": "URL is required",
  "code": "invalid_request",
  "message": "URL is required",
  "hint": "Send a JSON body with a \"url\" string.",
  "status": 400,
  "documentation": "https://shots.playbookmedia.io/docs#errors"
}

Sandbox

There is no separate sandbox host. Send utility endpoints only disposable public inputs. Tenant API calls can read or mutate workspace data and may consume plan quotas, so use a test workspace.

Building an agent

Load /openapi.json directly as a function-calling tool definition. Every operation carries a unique operationId, a description, typed parameters, and a response schema. Any page on this site also serves Markdown when asked:

curl -H "Accept: text/markdown" https://shots.playbookmedia.io/docs

CLI and MCP server

No official CLI tool and no MCP server are published yet. The curl examples above are the supported command-line path. If you want either one, email us.

Support

Email bugs and feature requests to [email protected], or reach the maintainers through the contact page.