API documentation | Richscripts Shots

FEWER MOVING PARTS

Your first screenshot.
One API call.

Send a URL and your API key. Get image bytes back. Save them to a file, upload them to your storage, or add them to your workflow.

Bearer authentication
PNG, JPEG, WebP or PDF response
URL or raw HTML input
Element, region and Retina captures
Credits charged only on success
Clear JSON errors on failure

Download OpenAPI specification ↓

cURL · POST /v1/screenshot

Example language

Request options

Parameter	Default	Details
`url`	url or html	Public HTTP(S) URL, up to 2,048 characters. Ports 80 / 443.
`html`	url or html	Markup to render instead of a URL, up to 200,000 characters. POST /v1/screenshot only.
`width / height`	1440 / 900	Width 320–2560 px; height 240–2560 px.
`format`	png	png, jpeg, webp or pdf.
`quality`	85	JPEG and WebP quality, 1–100.
`deviceScaleFactor`	1	1–3 for Retina/high-DPI images. Output is width × factor pixels.
`selector`	—	Capture only the first element matching a CSS selector.
`clipX / clipY / clipWidth / clipHeight`	—	Capture a rectangular region (all four required).
`waitUntil`	domcontentloaded	domcontentloaded, load or networkidle.
`waitForSelector`	—	Wait up to 10 s for an element to be visible; refunded if it never appears.
`hideSelectors`	—	Up to 20 CSS selectors to hide (array, or comma-separated in GET).
`styles`	—	Custom CSS up to 5,000 characters (no @import or url()).
`darkMode`	false	Emulate prefers-color-scheme: dark.
`mobile / landscape`	false	Mobile touch emulation; landscape swaps a portrait viewport.
`timezone / locale`	—	IANA timezone (Europe/Berlin) and locale (de-DE).
`fullPage`	false	Up to 12,000 px tall and 24 million pixels.
`delay`	500	Wait 0–3000 ms after the initial page loads.

One concurrent capture per account, up to 20 requests/minute. HTTP 401: invalid key · 402: no credits · 422: capture failed · 429: busy or rate limited · 504: timeout. Retry 429 after the Retry-After interval when present. WebSockets, service workers, and non-GET/HEAD page requests are disabled. Enable mobile touch emulation for mobile layouts.

GET captures and signed links

Send a Bearer API key in the Authorization header when using GET /take. Do not put permanent API keys in query strings.

curl 'https://shots.richscripts.com/take?url=https%3A%2F%2Fyahoo.com&format=png' \
  -H 'Authorization: Bearer YOUR_API_KEY' --output screenshot.png

POST the same capture settings to /api/capture-links with your Bearer key. The response contains a signed URL, expiry and singleUse flag. Alternatively, create a link in the playground.

Links expire after 10 minutes and permit one capture attempt. Anyone holding the link can use it. A failed render refunds the credit but consumes the link; create a new link to retry. Link creation is free. GET capture links cannot be used as permanent image hosting.

Capacity and diagnostics

Two active workers and four waiting requests, with a maximum queue wait of five seconds. One active or waiting request per account. A full queue returns HTTP 429 and Retry-After. Keep the X-Request-Id response header when reporting an error.

Cleaner screenshots

Set blockAds, blockCookieBanners and blockChats independently to true. These options work with POST, GET and signed links.

Ad and chat requests are filtered against a bundled provider list. Known banners, widgets and ad containers are hidden before capture, including accessible frames. Coverage is best effort: custom overlays, closed shadow roots and empty ad placeholders may remain. No consent buttons are clicked. Rules ship with application updates, not a live subscription database.

Use Shots from AI agents (MCP)

Download mcp.mjs (Node 18+, no dependencies). Add it to Claude Desktop, Claude Code, Cursor or another MCP client:

{
  "mcpServers": {
    "shots": {
      "command": "node",
      "args": ["/path/to/mcp.mjs"],
      "env": { "SHOTS_API_KEY": "YOUR_API_KEY" }
    }
  }
}

The agent gets a take_screenshot tool that accepts a URL or HTML plus the options above, and receives the image directly. Each successful capture uses one credit.

INTEGRATION CHECKLIST

Build a predictable capture workflow.

Keep API keys on your server

Send your key in the Authorization header. Never embed a permanent key in public frontend code or query parameters.

Handle the response type

A successful response contains image bytes. Failures return JSON. Check the HTTP status before saving the response as an image.

Retry with care

For HTTP 429, respect Retry-After. After a connection timeout, check recent requests before retrying; duplicate successful captures use additional credits.

Know the operational limits

Two active workers, four waiting requests and a five-second maximum queue wait. Each account can have one active or waiting capture and make up to 20 requests per minute. Render time is capped at 35 seconds.

Requests target public HTTP(S) pages on standard ports. Private networks, WebSockets, service workers and page requests other than GET/HEAD are blocked. Custom CSS is supported; login cookies and JavaScript injection are not.

Manage API keys →

Your first screenshot.One API call.