API Documentation
Integrate ShotPort powerful screenshot capabilities into your applications with our simple and robust API.
API Endpoint
All API requests should be made to the following ShotPort API endpoint:
- Main Endpoint:
http://localhost:3000/api/screenshot
This endpoint intelligently routes your request to our screenshot generation service. The underlying screenshot service URL is managed by site administrators and is not directly exposed to API users.
Authentication
All API requests must be authenticated using an API key. Include your API key as a query parameter named apiKey. You can generate and manage your API keys from your user dashboard (coming soon).
Endpoint: Take Screenshot
To capture a screenshot, make a GET request to one of the base URLs with the desired parameters.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | N/A | The full URL of the website to capture (e.g., https://example.com). |
format | string | No | png | Output image format. Options: png, jpeg, webp. |
quality | number | No | 80 (jpeg/webp) | Image quality for lossy formats (1-100). |
width | number | No | 1280 | Viewport width in pixels. |
height | number | No | 720 | Viewport height in pixels. If fullPage is true, this acts as min-height. |
fullPage | boolean | No | false | Capture the entire scrollable page. |
delay | number | No | 0 | Delay in milliseconds before taking the screenshot to allow content to load. |
userAgent | string | No | N/A | Custom user-agent string. |
jsCode | string | No | N/A | Base64 encoded JavaScript to execute on the page before capture. |
hide | string | No | N/A | Comma-separated CSS selectors of elements to hide. |
cookies | string | No | N/A | Base64 encoded JSON array of cookie objects (name, value, domain, path, etc.). |
headers | string | No | N/A | Base64 encoded JSON object of custom HTTP headers. |
clipSelector | string | No | N/A | CSS selector of an element to clip the screenshot to. Overrides clipX/Y/Width/Height. |
clipX | number | No | N/A | X-coordinate for clipping region. |
clipY | number | No | N/A | Y-coordinate for clipping region. |
clipWidth | number | No | N/A | Width of clipping region. |
clipHeight | number | No | N/A | Height of clipping region. |
responseType | string | No | image | How the API responds. Options: image (direct image stream), json (JSON with image URL or base64 data - future). |
apiKey | string | Yes | N/A | Your unique API key (provided in your dashboard). |
Using cURL (GET Requests):
Here are a few examples of how to use the API with cURL. Replace YOUR_API_KEY with your actual API key.
1. Basic Screenshot (defaults to PNG):
curl -o screenshot.png "http://localhost:3000/api/screenshot?url=https://example.com&apiKey=YOUR_API_KEY"
2. JPEG Screenshot with Specific Quality:
curl -o screenshot.jpg "http://localhost:3000/api/screenshot?url=https://example.com&format=jpeg&quality=75&apiKey=YOUR_API_KEY"
3. Full Page Screenshot with Delay:
curl -o fullpage.png "http://localhost:3000/api/screenshot?url=https://example.com&fullPage=true&delay=2000&apiKey=YOUR_API_KEY"
4. Specific Viewport Size (e.g., Mobile):
curl -o mobile.png "http://localhost:3000/api/screenshot?url=https://example.com&width=375&height=667&apiKey=YOUR_API_KEY"
5. WebP Format with Custom User-Agent:
curl -o custom.webp "http://localhost:3000/api/screenshot?url=https://example.com&format=webp&userAgent=MyCustomBrowser/1.0&apiKey=YOUR_API_KEY"
You can also directly use these URLs (with your API key and properly encoded parameters) in a browser's address bar or as the src for an image tag:
http://localhost:3000/api/screenshot?url=https://example.com&format=png&apiKey=YOUR_API_KEY
Response
By default (responseType=image), the API directly returns the image binary data with the appropriate Content-Type header (e.g., image/png, image/jpeg). Future responseType options like json may provide a JSON object containing the image URL or base64 encoded data.
Error Handling
The API uses standard HTTP status codes to indicate success or failure:
200 OK: Screenshot generated successfully.400 Bad Request: Missing or invalid parameters (e.g., no URL, invalid format). Check response body for details.401 Unauthorized: Invalid or missing API key.403 Forbidden: API key valid, but insufficient plan quota or access rights.429 Too Many Requests: Rate limit exceeded.500 Internal Server Error: An error occurred on our end while processing the request.502 Bad Gateway / 504 Gateway Timeout: Issues with the target URL or upstream services.