Screenshots API

curl --request POST \
  --url https://api.example.com/api/screenshot \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "device": "<string>",
  "width": 123,
  "height": 123,
  "format": "<string>",
  "quality": 123,
  "fullPage": true,
  "delay": 123,
  "selector": "<string>",
  "mockup": "<string>",
  "aiRemoval": {}
}
'

import requests

url = "https://api.example.com/api/screenshot"

payload = {
    "url": "<string>",
    "device": "<string>",
    "width": 123,
    "height": 123,
    "format": "<string>",
    "quality": 123,
    "fullPage": True,
    "delay": 123,
    "selector": "<string>",
    "mockup": "<string>",
    "aiRemoval": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    device: '<string>',
    width: 123,
    height: 123,
    format: '<string>',
    quality: 123,
    fullPage: true,
    delay: 123,
    selector: '<string>',
    mockup: '<string>',
    aiRemoval: {}
  })
};

fetch('https://api.example.com/api/screenshot', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/screenshot",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'device' => '<string>',
    'width' => 123,
    'height' => 123,
    'format' => '<string>',
    'quality' => 123,
    'fullPage' => true,
    'delay' => 123,
    'selector' => '<string>',
    'mockup' => '<string>',
    'aiRemoval' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/screenshot"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/screenshot")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/screenshot")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "429": {},
  "500": {}
}

POST

api

screenshot

Screenshots API

curl --request POST \
  --url https://api.example.com/api/screenshot \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "device": "<string>",
  "width": 123,
  "height": 123,
  "format": "<string>",
  "quality": 123,
  "fullPage": true,
  "delay": 123,
  "selector": "<string>",
  "mockup": "<string>",
  "aiRemoval": {}
}
'

import requests

url = "https://api.example.com/api/screenshot"

payload = {
    "url": "<string>",
    "device": "<string>",
    "width": 123,
    "height": 123,
    "format": "<string>",
    "quality": 123,
    "fullPage": True,
    "delay": 123,
    "selector": "<string>",
    "mockup": "<string>",
    "aiRemoval": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: '<string>',
    device: '<string>',
    width: 123,
    height: 123,
    format: '<string>',
    quality: 123,
    fullPage: true,
    delay: 123,
    selector: '<string>',
    mockup: '<string>',
    aiRemoval: {}
  })
};

fetch('https://api.example.com/api/screenshot', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/screenshot",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'device' => '<string>',
    'width' => 123,
    'height' => 123,
    'format' => '<string>',
    'quality' => 123,
    'fullPage' => true,
    'delay' => 123,
    'selector' => '<string>',
    'mockup' => '<string>',
    'aiRemoval' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/screenshot"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/screenshot")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/screenshot")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"device\": \"<string>\",\n  \"width\": 123,\n  \"height\": 123,\n  \"format\": \"<string>\",\n  \"quality\": 123,\n  \"fullPage\": true,\n  \"delay\": 123,\n  \"selector\": \"<string>\",\n  \"mockup\": \"<string>\",\n  \"aiRemoval\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

The URL of the webpage to capture

Viewport Configuration

string

Predefined device viewport. Options:

desktop (1920×1080)
laptop (1366×768)
tablet (768×1024)
mobile (375×812)

number

Custom viewport width in pixels (ignored if device is specified)

number

Custom viewport height in pixels (ignored if device is specified)

Output Options

string

default:"png"

Output format:

png: High quality with transparency
jpeg: Smaller file size
pdf: Document format (mockups not available)

number

default:"100"

Image quality for JPEG format (1-100)

boolean

default:"false"

Whether to capture the full scrollable page

Capture Options

number

default:"0"

Delay in milliseconds before capturing (0-10000). Useful for:

Waiting for animations
Loading dynamic content
Ensuring popups appear

string

CSS selector to capture specific element. Examples:

#hero-section
.product-card
[data-testid="main-content"]

Mockup Options

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

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

object

Invalid request parameters

{
  "error": "Invalid request parameters",
  "details": [
    {
      "code": "invalid_type",
      "path": ["quality"],
      "message": "Expected number, received string"
    }
  ]
}

object

Missing or invalid API token

{
  "error": "Invalid API key"
}

object

Rate limit exceeded

{
  "error": "Rate limit exceeded",
  "reset": 1635724800
}

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

const response = await fetch('https://screenshotly.app/api/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    device: 'desktop',
    format: 'png',
  }),
});

const screenshot = await response.blob();

import requests

response = requests.post(
    'https://screenshotly.app/api/screenshot',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
    },
    json={
        'url': 'https://example.com',
        'device': 'desktop',
        'format': 'png',
    },
)

screenshot = response.content

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

const response = await fetch('https://screenshotly.app/api/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    device: 'desktop',
    mockup: 'browser-light',
    format: 'png',
    aiRemoval: {
      enabled: true,
      types: ['cookie-banner', 'ad', 'chat-widget'],
      confidence: 0.8
    },
  }),
});

const screenshot = await response.blob();

import requests

response = requests.post(
    'https://screenshotly.app/api/screenshot',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
    },
    json={
        'url': 'https://example.com',
        'device': 'desktop',
        'mockup': 'browser-light',
        'format': 'png',
        'aiRemoval': {
            'enabled': True,
            'types': ['cookie-banner', 'ad', 'chat-widget'],
            'confidence': 0.8
        },
    },
)

screenshot = response.content

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

const response = await fetch('https://screenshotly.app/api/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'pdf',
    fullPage: true,
    delay: 1000,
  }),
});

const pdf = await response.blob();

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

Getting Started

API Reference

Guides

Resources

Screenshots API

Screenshots API

Endpoint

Authentication

Request Parameters

Core Parameters

Viewport Configuration

Output Options

Capture Options

Mockup Options

AI Element Removal

Response

Success Response

Headers

Error Responses

Examples

Basic Screenshot

With AI Element Removal and Mockup

Full Page PDF

Rate Limits

Best Practices

Format Selection

Performance Tips

Security Considerations

​Screenshots API

​Endpoint

​Authentication

​Request Parameters

​Core Parameters

​Viewport Configuration

​Output Options

​Capture Options

​Mockup Options

​AI Element Removal

​Response

​Success Response

​Headers

​Error Responses

​Examples

​Basic Screenshot

​With AI Element Removal and Mockup

​Full Page PDF

​Rate Limits

​Best Practices

​Format Selection

​Performance Tips

​Security Considerations

Screenshots API

Endpoint

Authentication

Request Parameters

Core Parameters

Viewport Configuration

Output Options

Capture Options

Mockup Options

AI Element Removal

Response

Success Response

Headers

Error Responses

Examples

Basic Screenshot

With AI Element Removal and Mockup

Full Page PDF

Rate Limits

Best Practices

Format Selection

Performance Tips

Security Considerations