API Documentation

Everything you need to integrate Shots by Scrappy into your applications

Quick Start
Get up and running in minutes
1

Get your API key

Sign up and generate your API key from the dashboard

2

Make your first request

Send a POST request to capture your first screenshot

3

Download your screenshot

Use the returned URL to access your high-quality screenshot

API Reference

Base URL

https://shots.scrappy.services/v1

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints

POST/screenshot

Capture a screenshot of any website

Request Body:

{ "url": "https://example.com", // Required: URL to screenshot "width": 1920, // Optional: Viewport width (100-4000) "height": 1080, // Optional: Viewport height (100-4000) "device": "desktop", // Optional: desktop, mobile, tablet "format": "png", // Optional: png, jpeg, webp "quality": 90, // Optional: 1-100 (for jpeg/webp) "fullPage": true // Optional: Capture full page }

Response:

{ "id": "screenshot_1234567890", "url": "https://example.com", "status": "success", "screenshotUrl": "https://cdn-shots.scrappy.services/...", "thumbnailUrl": "https://cdn-shots.scrappy.services/...", "metadata": { "width": 1920, "height": 1080, "device": "desktop", "format": "png", "fileSize": "245 KB", "timestamp": "2024-01-20T14:30:00.000Z" } }
GET/screenshots

List all your screenshots with pagination

Query Parameters:

?page=1&limit=20&status=success&device=desktop
GET/screenshots/:id

Get details of a specific screenshot

GET/usage

Get your API usage statistics

Code Examples
Ready-to-use code snippets in popular languages
curl -X POST https://shots.scrappy.services/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1920,
    "height": 1080,
    "device": "desktop",
    "format": "png",
    "fullPage": true
  }'
Error Codes
Understanding API error responses
400Bad Request

Invalid request parameters

401Unauthorized

Invalid or missing API key

429Rate Limited

Too many requests

500Server Error

Internal server error

Best Practices

Secure your API keys

Never expose API keys in client-side code. Use environment variables and server-side requests.

Handle rate limits

Implement exponential backoff when you receive 429 responses.

Cache screenshots

Store screenshots locally when possible to reduce API calls and improve performance.

Validate URLs

Always validate URLs on your end before sending requests to avoid unnecessary API calls.