ScreenshotPro:DEV | Documentation

API Reference

Resources

ScreenshotPro API Reference

Introduction

The ScreenshotPro API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.screenshotpro.com

Authentication

The ScreenshotPro API uses API keys to authenticate requests. You can view and manage your API keys in the ScreenshotPro dashboard.

Authentication to the API is performed via the X-API-Key header. Provide your API key as the value for this header in all API requests. 

curl -X POST https://api.screenshotpro.com/api/screenshot \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Important Security Notice

Your API key carries many privileges, so be sure to keep it secure! Do not share your API key in publicly accessible areas such as GitHub, client-side code, etc.

Take Screenshot

POST /api/screenshot

Capture a screenshot of a webpage

Request Parameters

Parameter Type Required Description
url string Yes The URL of the webpage to capture
format string No Format of the screenshot (png, jpeg, webp, pdf). Default: png
resolution string No Resolution in format 'widthxheight' (e.g., '1280x720'). Default: 1280x720
fullpage boolean No Capture full scrollable page. Default: false
delay integer No Delay in milliseconds before capturing the screenshot. Default: 0
viewport string No Custom viewport size in format 'widthxheight'. Default: Based on resolution
device string No Device emulation (e.g., 'iPhone X', 'iPad'). Default: None
watermark boolean No Add watermark to the screenshot. Default: true
password_protect boolean No Protect the screenshot with a password. Default: false
password string Only if password_protect=true Password to protect the screenshot
webhook_url string No URL to send a webhook notification when the screenshot is ready

Example Request

curl -X POST https://api.screenshotpro.com/api/screenshot \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "resolution": "1920x1080",
    "fullpage": true,
    "delay": 500,
    "watermark": false
  }'

Example Response

{
  "success": true,
  "message": "Screenshot task is queued successfully",
  "data": {
    "id": "abc123",
    "status": "pending",
    "url": "https://example.com"
  }
}

Note

Screenshot generation is an asynchronous process. The API immediately returns a response with a screenshot ID that you can use to check the status of the screenshot.

Screenshot Status

GET /api/screenshot/{id}

Check the status of a screenshot

Path Parameters

Parameter Type Required Description
id string Yes The ID of the screenshot

Example Request

curl https://api.screenshotpro.com/api/screenshot/abc123 \
  -H "X-API-Key: your_api_key"

Example Response (Pending)

{
  "success": true,
  "message": "Screenshot status retrieved",
  "data": {
    "id": "abc123",
    "status": "pending",
    "url": "https://example.com",
    "created_at": "2025-03-28T12:34:56Z",
    "format": "png",
    "is_available": false,
    "screenshot_url": null,
    "error": null
  }
}

Example Response (Completed)

{
  "success": true,
  "message": "Screenshot status retrieved",
  "data": {
    "id": "abc123",
    "status": "completed",
    "url": "https://example.com",
    "created_at": "2025-03-28T12:34:56Z",
    "format": "png",
    "is_available": true,
    "screenshot_url": "https://cdn.screenshotpro.com/screenshots/abc123.png",
    "error": null
  }
}

Response Format

All API responses follow a consistent format:

Field Type Description
success boolean Indicates whether the request was successful
message string A human-readable message describing the result
data object The response data

Error Codes

When an error occurs, the API returns an appropriate HTTP status code and a descriptive error message.

Status Code Description
400 - Bad Request The request was invalid or malformed
401 - Unauthorized Invalid API key or authentication failure
403 - Forbidden The API key doesn't have permission to perform the request or rate limit exceeded
404 - Not Found The requested resource doesn't exist
429 - Too Many Requests Rate limit exceeded
500, 502, 503, 504 - Server Errors Something went wrong on our end

Example Error Response

{
  "success": false,
  "message": "Validation error",
  "data": {
    "url": [
      "The url field is required."
    ]
  }
}