API REFERENCE

API Documentation

Everything you need to capture screenshots programmatically.

Authentication

Authenticate using your API key. Pass it as a Bearer token or query parameter.

Header (recommended)

Authorization: Bearer fs_your_api_key

Query parameter

?key=fs_your_api_key

Endpoint

GET https://framesnap.dev/v1/screenshot

Parameters

All parameters are passed as query string params.

Parameter	Type	Default	Description
url	string	required	URL to capture
width	int	1280	Viewport width (320-3840)
height	int	800	Viewport height (240-2160)
full_page	bool	false	Capture entire scrollable page
format	string	png	Output format: png, jpeg, or pdf
quality	int	-	JPEG quality (1-100)
delay	int	0	Wait ms before capture (0-5000)
dark_mode	bool	false	Use dark color scheme
scale	float	1.0	Device scale factor (0.5-3.0)
block_ads	bool	false	Block common ad networks
response_type	string	image	image (raw bytes) or json (base64)
callback_url	string	-	HTTPS URL for async webhook delivery

Code Examples

curl "https://framesnap.dev/v1/screenshot?url=stripe.com&width=1280&format=png" \
  -H "Authorization: Bearer fs_your_api_key" \
  --output screenshot.png

import requests

response = requests.get(
    "https://framesnap.dev/v1/screenshot",
    params={
        "url": "stripe.com",
        "width": 1280,
        "format": "png",
        "full_page": True,
    },
    headers={"Authorization": "Bearer fs_your_api_key"},
)

with open("screenshot.png", "wb") as f:
    f.write(response.content)

const params = new URLSearchParams({
  url: "stripe.com",
  width: "1280",
  format: "png",
  full_page: "true",
});

const response = await fetch(
  `https://framesnap.dev/v1/screenshot?${params}`,
  { headers: { Authorization: "Bearer fs_your_api_key" } }
);

const buffer = await response.arrayBuffer();
fs.writeFileSync("screenshot.png", Buffer.from(buffer));

package main

import (
    "io"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://framesnap.dev/v1/screenshot?url=stripe.com&width=1280&format=png", nil)
    req.Header.Set("Authorization", "Bearer fs_your_api_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    f, _ := os.Create("screenshot.png")
    defer f.Close()
    io.Copy(f, resp.Body)
}

Response Formats

Image (default)

Returns raw image bytes with appropriate Content-Type header.

Content-Type: image/png
X-Screenshot-Size: 847293

JSON (response_type=json)

Returns metadata and base64-encoded image.

{
  "url": "https://stripe.com",
  "width": 1280,
  "height": 800,
  "format": "png",
  "full_page": false,
  "file_size": 847293,
  "image": "iVBORw0KGgo..."
}

Webhooks

Pass a callback_url to receive the screenshot asynchronously. The API returns immediately with a 202 Accepted and POSTs the result to your URL when ready.

Request

curl "https://framesnap.dev/v1/screenshot?url=stripe.com&callback_url=https://yourapp.com/webhook" \
  -H "Authorization: Bearer fs_your_api_key"

# Returns immediately:
# {"screenshot_id": "abc-123", "status": "processing", "callback_url": "..."}

Callback payload (success)

{
  "screenshot_id": "abc-123",
  "status": "completed",
  "url": "https://stripe.com",
  "image_url": "https://storage.supabase.co/...",
  "width": 1280,
  "height": 800,
  "format": "png",
  "file_size": 847293
}

Callback payload (failure)

{
  "screenshot_id": "abc-123",
  "status": "failed",
  "error": "Screenshot capture timed out"
}

Error Codes

Status	Meaning
400	Invalid URL or parameters
401	Missing or invalid API key
429	Monthly rate limit exceeded or server busy
502	Failed to capture screenshot (target site error)
504	Screenshot capture timed out (30s limit)

// All errors return JSON:
{"detail": "Monthly limit of 100 screenshots reached"}

Rate Limits

Rate limits are per API key, tracked monthly.

Plan	Price	Monthly Limit	API Keys
Free	$0	100	1
Starter	$19/mo	5,000	3
Pro	$49/mo	25,000	5
Scale	$149/mo	100,000	5

View Pricing

MCP Server

Give AI coding agents the ability to take screenshots. The @framesnap/mcp-server works with Claude Code, Cursor, Windsurf, and any MCP-compatible tool. Learn more →

claude mcp add framesnap -e FRAMESNAP_API_KEY=fs_your_key -- npx -y @framesnap/mcp-server

// Add to .cursor/mcp.json or MCP client config:
{
  "mcpServers": {
    "framesnap": {
      "command": "npx",
      "args": ["-y", "@framesnap/mcp-server"],
      "env": { "FRAMESNAP_API_KEY": "fs_your_key" }
    }
  }
}

Exposes framesnap_screenshot tool. Supports save_path to write screenshots to disk.

CLI Tool

Screenshot any website from the command line with the framesnap CLI. Great for scripting and CI/CD pipelines. Learn more →

Install & configure

npm install -g framesnap
framesnap config set api-key fs_your_key

Usage

framesnap https://stripe.com -o screenshot.png
framesnap https://mysite.com --full-page --dark-mode -o full.png
framesnap https://mysite.com -w 390 -h 844 -o mobile.png