Screenshots API

The PeekShot Screenshot API allows you to capture high-quality screenshots of web pages programmatically. Easily integrate it into your applications for website monitoring, SEO tracking, and more.

Take Screenshot

Create a new screenshot by sending a POST request with the target URL and configuration options.

POST https://api.peekshot.com/api/v1/screenshots

Request Headers

Header	Required	Description
x-api-key	Yes	Your unique API key for authentication
Content-Type	Yes	Must be application/json

Request Body Parameters

Send a JSON payload with the following parameters:

Parameter	Type	Required	Description
project_id	string	Yes	Unique project identifier
url	string	Yes	The website URL to capture
width	string	No	Screenshot width (default: 1680)
height	string	No	Screenshot height (default: 867)
inject_css	string	No	Custom CSS to apply
inject_js	string	No	Custom JavaScript to apply
file_type	string	No	Image format (jpeg, png, etc.)
retina	string	No	”true” for high-resolution screenshots
delay	string	No	Time (in seconds) to wait before capturing
full_page	string	No	”true” to capture the entire page, “false” for viewport only
disable_javascript	string	No	”true” to disable JavaScript execution
emulate_device	string	No	Supported device name for mobile emulation
disable_animations	string	No	”true” to disable animations
proxy_url	string	No	HTTP proxy URL (supports authentication)
custom_header	string	No	Inject custom header into request
element_selector	string	No	Target a specific element. Use CSS selector (e.g., “#header”) or XPath with “xpath=” prefix (e.g., “xpath=//div[@id=‘main’]“)

Using a Proxy

You can route screenshot captures through a custom HTTP proxy using the proxy_url option.

Proxy Limitations

Only HTTP proxies are supported. HTTPS and SOCKS5 proxies are not supported.

Proxy URL Syntax

http://username:password@host:port

Example Requests

Basic Screenshot

{
  "project_id": "1",
  "url": "https://example.com"
}

Custom Dimensions and Format

{
  "project_id": "1",
  "url": "https://example.com",
  "width": "1920",
  "height": "1080",
  "file_type": "png",
  "retina": "true"
}

Full Page with Custom CSS

{
  "project_id": "1",
  "url": "https://example.com",
  "width": "1680",
  "height": "867",
  "inject_css": ".container { background: red !important; }",
  "full_page": "true",
  "delay": "2"
}

Element-Specific Screenshot

{
  "project_id": "1",
  "url": "https://example.com",
  "element_selector": "#main-content",
  "file_type": "png"
}

Mobile Device Emulation

{
  "project_id": "1",
  "url": "https://example.com",
  "emulate_device": "iPhone 13",
  "full_page": "true"
}

Code Examples

cURL

curl --location 'https://api.peekshot.com/api/v1/screenshots' \
  --header 'x-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
      "project_id": "1",
      "url": "https://example.com",
      "width": "1680",
      "height": "867",
      "file_type": "jpeg",
      "retina": "true",
      "delay": "0",
      "full_page": "false",
      "disable_javascript": "false"
  }'

Node.js

const axios = require("axios");

const takeScreenshot = async () => {
  const data = {
    project_id: "1",
    url: "https://example.com",
    width: "1680",
    height: "867",
    file_type: "jpeg",
    retina: "true",
    delay: "0",
    full_page: "false",
    disable_javascript: "false",
  };

  const config = {
    method: "post",
    maxBodyLength: Infinity,
    url: "https://api.peekshot.com/api/v1/screenshots",
    headers: {
      "x-api-key": "your-api-key",
      "Content-Type": "application/json",
    },
    data: JSON.stringify(data),
  };

  try {
    const response = await axios.request(config);
    console.log(JSON.stringify(response.data));
    return response.data;
  } catch (error) {
    console.log(error);
    throw error;
  }
};

Python

import requests
import json

def take_screenshot():
    url = "https://api.peekshot.com/api/v1/screenshots"
    api_key = "your-api-key"

    # Request payload
    data = {
        "project_id": "1",
        "url": "https://example.com",
        "width": "1680",
        "height": "867",
        "file_type": "jpeg",
        "retina": "true",
        "delay": "0",
        "full_page": "false",
        "disable_javascript": "false"
    }

    # Headers
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }

    # Sending POST request
    response = requests.post(url, headers=headers, data=json.dumps(data))

    # Print response
    print("Response Code:", response.status_code)
    print("Response Body:", response.json())

    return response.json()

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	// Define the request payload
	data := map[string]string{
		"project_id": "1",
		"url": "https://example.com",
		"width": "1680",
		"height": "867",
		"file_type": "jpeg",
		"retina": "true",
		"delay": "0",
		"full_page": "false",
		"disable_javascript": "false",
	}

	// Convert the data to JSON
	jsonData, err := json.Marshal(data)
	if err != nil {
		fmt.Println("Error marshalling JSON:", err)
		return
	}

	// Create an HTTP request
	req, err := http.NewRequest("POST", "https://api.peekshot.com/api/v1/screenshots", bytes.NewBuffer(jsonData))
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	// Set headers
	req.Header.Set("x-api-key", "your-api-key")
	req.Header.Set("Content-Type", "application/json")

	// Send the request using http.Client
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	// Read and print the response
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Error reading response:", err)
		return
	}

	fmt.Println("Response:", string(body))
}

Java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import org.json.JSONObject;

public class ScreenshotAPI {
    public static void main(String[] args) {
        try {
            // Define API URL
            URL url = new URL("https://api.peekshot.com/api/v1/screenshots");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            // Set request method to POST
            conn.setRequestMethod("POST");
            conn.setRequestProperty("x-api-key", "your-api-key");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            // Create JSON payload
            JSONObject json = new JSONObject();
            json.put("project_id", "1");
            json.put("url", "https://example.com");
            json.put("width", "1680");
            json.put("height", "867");
            json.put("file_type", "jpeg");
            json.put("retina", "true");
            json.put("delay", "0");
            json.put("full_page", "false");
            json.put("disable_javascript", "false");

            // Send JSON data
            OutputStream os = conn.getOutputStream();
            os.write(json.toString().getBytes("UTF-8"));
            os.flush();
            os.close();

            // Read response
            int responseCode = conn.getResponseCode();
            BufferedReader reader = new BufferedReader(new InputStreamReader(
                    (responseCode >= 200 && responseCode < 300) ? conn.getInputStream() : conn.getErrorStream()));

            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            reader.close();

            // Print response
            System.out.println("Response: " + response.toString());

            // Close connection
            conn.disconnect();

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

PHP

<?php

$apiUrl = "https://api.peekshot.com/api/v1/screenshots";
$apiKey = "your-api-key";

// Prepare JSON payload
$data = [
    "project_id" => "1",
    "url" => "https://example.com",
    "width" => "1680",
    "height" => "867",
    "file_type" => "jpeg",
    "retina" => "true",
    "delay" => "0",
    "full_page" => "false",
    "disable_javascript" => "false"
];

// Initialize cURL
$ch = curl_init($apiUrl);

// Set cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: $apiKey",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Check for errors
if (curl_errno($ch)) {
    echo "cURL Error: " . curl_error($ch);
} else {
    echo "Response (HTTP $httpCode): " . $response;
}

// Close cURL session
curl_close($ch);
?>

Ruby

require 'net/http'
require 'uri'
require 'json'

# API endpoint and API key
url = URI.parse("https://api.peekshot.com/api/v1/screenshots")
api_key = "your-api-key"

# Request payload
data = {
  "project_id" => "1",
  "url" => "https://example.com",
  "width" => "1680",
  "height" => "867",
  "file_type" => "jpeg",
  "retina" => "true",
  "delay" => "0",
  "full_page" => "false",
  "disable_javascript" => "false"
}

# Create HTTP request
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = (url.scheme == "https")

request = Net::HTTP::Post.new(url)
request["x-api-key"] = api_key
request["Content-Type"] = "application/json"
request.body = data.to_json

# Send request and get response
response = http.request(request)

# Print response
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"

Response

Success Response (201 Created)

{
  "status": "success",
  "message": "screenshot request added in queue",
  "data": {
    "url": "https://example.com",
    "requestId": 1,
    "creditRequired": 1,
    "organizationId": 1
  },
  "statusCode": 201
}

Response Fields

Field	Type	Description
status	string	Request status (“success” or “error”)
message	string	Descriptive message about the request
data	object	Response data containing request details
data.url	string	The URL that was captured
data.requestId	integer	Unique identifier for this screenshot request
data.creditRequired	integer	Number of credits consumed
data.organizationId	integer	Organization ID associated with the request
statusCode	integer	HTTP status code

Error Responses

Status Code	Error Message	Description
400	Invalid Request	Check your input parameters
403	Forbidden	Invalid or inactive API key
500	Internal Server Error	Something went wrong on our end

Best Practices

Performance Optimization

• Use appropriate dimensions for your use case to minimize processing time
• Set reasonable delay values (avoid unnecessary waiting)
• Choose optimal file formats (JPEG for photos, PNG for graphics)
• Use element selectors to capture specific parts of pages

Resource Management

• Monitor your credit usage through the API
• Implement proper error handling and retry logic
• Use projects to organize your screenshots

Quality Enhancement

• Use retina mode for high-DPI displays
• Inject CSS/JS to hide unwanted elements (ads, popups)
• Set appropriate delays for dynamic content
• Test with different device emulations for responsive designs

Technical Notes

• The API processes requests asynchronously.
• Large screenshots may take longer to process
• Ensure the provided URL is publicly accessible
• Proxy support is limited to HTTP proxies only
• Custom JavaScript injection runs after page load

For further assistance, contact hello@peekshot.com.

Next Steps

• Get Screenshot - Retrieve completed screenshots
• Screenshots List - List your screenshots
• Projects - Manage screenshot projects
• Supported Devices - Available device emulations