Skip to main content
POST
/
api
/
screenshot
{
  "400": {},
  "401": {},
  "429": {},
  "500": {}
}

​
Screenshots API

The Screenshots API allows you to capture high-quality screenshots of any webpage with customizable options and apply device mockups.

​
Endpoint

POST /api/screenshot
Base URL: https://screenshotly.app (or your deployed instance)

​
Authentication

All requests must include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_TOKEN

​
Request Parameters

​
Core Parameters

​
url
string
required
The URL of the webpage to capture

​
Viewport Configuration

​
device
string
Predefined device viewport. Options:
  • desktop (1920×1080)
  • laptop (1366×768)
  • tablet (768×1024)
  • mobile (375×812)
​
width
number
Custom viewport width in pixels (ignored if device is specified)
​
height
number
Custom viewport height in pixels (ignored if device is specified)

​
Output Options

​
format
string
default:"png"
Output format:
  • png: High quality with transparency
  • jpeg: Smaller file size
  • pdf: Document format (mockups not available)
​
quality
number
default:"100"
Image quality for JPEG format (1-100)
​
fullPage
boolean
default:"false"
Whether to capture the full scrollable page

​
Capture Options

​
delay
number
default:"0"
Delay in milliseconds before capturing (0-10000). Useful for:
  • Waiting for animations
  • Loading dynamic content
  • Ensuring popups appear
​
selector
string
CSS selector to capture specific element. Examples:
  • #hero-section
  • .product-card
  • [data-testid="main-content"]

​
Mockup Options

​
mockup
string
Apply a device mockup:
  • browser-light: Modern browser with light theme (1920×1036)
  • browser-dark: Modern browser with dark theme (1920×1036)
  • iphone-14: iPhone 14 Pro with Dynamic Island (1000×1760)
  • macbook-pro: Modern MacBook Pro (1980×1230)

​
AI Element Removal

​
aiRemoval
object
AI-powered element removal configuration:
{
  "enabled": boolean,
  "types": string[],  // Array of element types to remove
  "confidence": number  // Confidence threshold (0-1)
}
Available element types:
  • cookie-banner: Cookie consent banners and GDPR notices
  • newsletter: Newsletter signup forms and subscription prompts
  • chat-widget: Customer support chat widgets and messengers
  • social-overlay: Social media buttons and sharing widgets
  • ad: Advertisement elements and promotional content

​
Response

​
Success Response

  • Status: 200 OK
  • Content-Type: image/png, image/jpeg, or application/pdf
  • Body: Binary file content

​
Headers

Content-Type: image/png
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1635724800

​
Error Responses

​
400
object
Invalid request parameters
{
  "error": "Invalid request parameters",
  "details": [
    {
      "code": "invalid_type",
      "path": ["quality"],
      "message": "Expected number, received string"
    }
  ]
}
​
401
object
Missing or invalid API token
{
  "error": "Invalid API key"
}
​
429
object
Rate limit exceeded
{
  "error": "Rate limit exceeded",
  "reset": 1635724800
}
​
500
object
Internal server error
{
  "error": "Failed to capture screenshot"
}

​
Examples

​
Basic Screenshot

curl -X POST https://screenshotly.app/api/screenshot \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "format": "png"
  }' \
  --output screenshot.png

​
With AI Element Removal and Mockup

curl -X POST https://screenshotly.app/api/screenshot \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "mockup": "browser-light",
    "format": "png",
    "aiRemoval": {
      "enabled": true,
      "types": ["cookie-banner", "ad", "chat-widget"],
      "confidence": 0.8
    }
  }' \
  --output screenshot_with_mockup.png

​
Full Page PDF

curl -X POST https://screenshotly.app/api/screenshot \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "pdf",
    "fullPage": true,
    "delay": 1000
  }' \
  --output document.pdf

​
Rate Limits

Rate limits vary by plan:
  • Free: 500 requests/month
  • Pro: 5000 requests/month
Rate limit information is included in response headers: 
X-RateLimit-Limit: Your plan's limit
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Timestamp when limit resets

​
Best Practices

​
Format Selection

  • Use png for screenshots that require transparency or highest quality
  • Use jpeg with quality settings for optimal file size
  • Use pdf for document-style captures or when PDF format is required

​
Performance Tips

  • Set appropriate delay for dynamic content loading
  • Use fullPage: true only when necessary
  • Optimize JPEG quality based on your needs
  • Consider using mockups only when presentation is important

​
Security Considerations

  • Never expose API keys in client-side code
  • Use environment variables to store API keys
  • Validate URLs on your end before sending to the API
  • Be mindful of rate limits to avoid service interruption