Quick Start

Welcome to PeekShot documentation! This guide will show you how to capture your first screenshot using our API. You’ll learn the essential concepts that you’ll use in all of your screenshot requests - authentication, basic requests, and retrieving results.

You will learn

• How to set up your PeekShot account and get your credentials
• How to authenticate your API requests with API keys
• How to send basic screenshot requests to capture websites
• How to handle asynchronous processing and retrieve your results
• How to check screenshot status and get download URLs
• How to set up webhooks for automated notifications

Prerequisites

You need:

• ✅ PeekShot account
• ✅ Project ID
• ✅ API Key

Let’s get them in 60 seconds.

Step 1: Sign Up & Get Your Project

1. Sign up at peekshot.com
2. Access your dashboard - you’ll see a “Default” project automatically created
3. Copy your Project ID from the Overview section

🔍 Where to find Project ID: Dashboard → Overview → Projects table → ID column

Step 2: Generate Your API Key

1. Go to API Keys in your dashboard sidebar
2. Click “Create New Key”
3. Fill in:
   • Key Name: My First Key (or whatever you want)
   • Project: Leave empty for all projects, or select specific project
   • Monthly Limit: Leave empty for maximum credits
4. Copy the generated API key

🔒 Keep it secure - this key authenticates all your requests.

Step 3: Take Your First Screenshot

Here’s a basic request to capture peekshot.com:

cURL

curl -X POST https://api.peekshot.com/api/v1/screenshots \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "url": "https://peekshot.com"
  }'

JavaScript

const response = await fetch("https://api.peekshot.com/api/v1/screenshots", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project_id: "YOUR_PROJECT_ID",
    url: "https://peekshot.com"
  }),
});

const result = await response.json();
console.log(result);

Python

import requests

response = requests.post(
    "https://api.peekshot.com/api/v1/screenshots",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "project_id": "YOUR_PROJECT_ID",
        "url": "https://peekshot.com"
    }
)

result = response.json()
print(result)

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.peekshot.com/api/v1/screenshots");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "project_id" => "YOUR_PROJECT_ID",
    "url" => "https://peekshot.com"
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

What You’ll Get Back

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

Important: Make sure you pass a valid, publicly accessible website URL and a valid project ID.

Step 4: Get Your Screenshot URL

PeekShot processes screenshots asynchronously. You have two ways to get your screenshot:

Option A: Polling (Simple)

Check status every 10-15 seconds using the requestId from your response:

cURL

curl -X GET https://api.peekshot.com/api/v1/screenshots/1 \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

const checkStatus = async (requestId) => {
  const response = await fetch(
    `https://api.peekshot.com/api/v1/screenshots/${requestId}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  return response.json();
};

// Poll every 10 seconds using the requestId from your response
const result = await checkStatus(1); // Use the requestId from your response
console.log(result);

Option B: Webhooks (Recommended for Production)

1. Go to Webhooks in your dashboard sidebar
2. Click “Create New Webhook”
3. Fill in:
   • Name: My Screenshot Webhook
   • Webhook URL: Your endpoint (e.g., https://your-app.com/webhook)
   • Projects: Leave empty for all projects
4. PeekShot will POST to your URL when ready

When Complete, You’ll Get

For Polling:

{
  "status": "success",
  "message": "screenshot request status fetched successfully",
  "data": {
    "id": 1,
    "organizationId": 1,
    "projectId": 1,
    "status": "COMPLETE",
    "url": "https://peekshot.com/",
    "screenshotImageSize": 1012796,
    "options": {
      "delay": 0,
      "fresh": true,
      "width": 1680,
      "height": 867,
      "output": "json",
      "retina": false,
      "language": "en-GB,en-US;q=0.9,en;q=0.8",
      "block_ads": false,
      "dark_mode": false,
      "file_type": "jpeg",
      "full_page": false,
      "disable_javascript": false,
      "block_cookie_banner": false
    },
    "screenshotUrl": "https://peekshot.s3.ap-south-1.amazonaws.com/6/image.jpeg",
    "creditsRequired": 1,
    "duration": "9.864",
    "isActive": true,
    "createdAt": "2025-03-23T09:11:25.906Z",
    "updatedAt": "2025-03-23T09:11:25.906Z",
    "deletedAt": null,
    "deletedByUserId": null
  },
  "statusCode": 200
}

For Webhooks:

{
  "requestId": 1,
  "success": true,
  "fileUrl": "https://peekshot.s3.ap-south-1.amazonaws.com/20/1742720537605_aqi6.jpeg"
}

🎉 Your screenshot is ready! Access it directly at the screenshot_url or fileUrl.

What Just Happened?

1. You authenticated with your API key
2. You sent a request to capture peekshot.com
3. PeekShot processed it asynchronously (takes 2-5 seconds)
4. You got a secure S3 URL to your screenshot

Next Steps

Ready for more? Check out the Take Screenshot API for:

• Custom viewport sizes
• Device emulation (iPhone, Android, etc.)
• Full-page screenshots
• CSS injection
• Custom delays
• Multiple output formats

Common Issues

• Invalid API Key: Make sure you copied the full key from dashboard
• Invalid Project ID: Check the ID column in your Projects table
• Invalid URL: Ensure the website is publicly accessible
• Rate Limits: Free accounts have generous limits, upgrade for more

---

That’s it! You’ve taken your first screenshot with PeekShot. The API is designed to be this simple.