# SCRNIFY.com API Documentation > **Beta Notice**: This API is currently in beta. The documentation and API endpoints may change without prior notice until we reach a stable release. This API allows you to capture screenshots and video recordings of web pages with customizable parameters. ## Base URL
{process.env.NEXT_PUBLIC_API_URL}capture
## Authentication
There are two types of API keys available for authentication:
### Simple API Key
Basic authentication using only the API key:
```
?key=your_api_key
```
### Signed API Key
Enhanced security by signing requests. Requires both the API key and a signature:
```
?key=your_api_key&signature=generated_signature&cache_ttl=3600
```
Requirements for signed API keys:
- The signature must be 64 characters long
- `cache_ttl` parameter is required
- Signature must be generated using HMAC-SHA256
#### Generating Signatures
To generate a valid signature:
1. Create an HMAC-SHA256 hash of the remaining query string using your API key's secret
2. Convert the hash to a hexadecimal string
Example (Node.js):
```javascript
const crypto = require('crypto');
function generateSignature(queryString, secret) {
const hmac = crypto.createHmac('sha256', secret);
hmac.update(queryString);
return hmac.digest('hex');
}
// Example usage
const params = new URLSearchParams({
key: 'your_api_key',
url: 'https://example.com',
type: 'image',
format: 'png',
width: '1920',
height: '1080',
cache_ttl: '3600'
});
const signature = generateSignature(params.toString(), 'your_api_secret');
params.append('signature', signature);
const finalUrl = `${baseUrl}?${params.toString()}`;
```
Note: The signature verification will check both the encoded and decoded query strings to handle URL encoding differences.
## Core Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | The URL of the webpage to capture (must be URL-encoded) |
| `type` | string | Yes | Type of capture: `image` or `video` |
| `format` | string | Yes | Output format (see Format Options below) |
| `width` | number | Yes | Viewport width in pixels |
| `height` | number | * | Viewport height in pixels. Required if `fullPage=false`, ignored if `fullPage=true` |
| `fullPage` | boolean | No | Whether to capture the full page length (default: false) |
| `cache_ttl` | number | ** | Cache duration in seconds (max: 30 days). Required for signed API keys |
## Format Options
### Image Formats
- `jpeg`: JPEG format
- Additional parameter: `quality` (1-100, default: 100)
- `png`: PNG format
- `gif`: GIF format
### Video Formats
- `mp4`: MP4 format
- `webm`: WebM format
- `gif`: Animated GIF format
## Additional Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `duration` | number | Duration in seconds for video capture (default: 1). Only applicable when `type=video` |
| `waitUntil` | string | Event to wait for before capture. Options: |
| | | - `firstPaint`: When the first pixel is painted by the browser |
| | | - `firstContentfulPaint`: When the first text, image, canvas, or SVG is painted |
| | | - `firstImagePaint`: When the first image element is painted |
| | | - `firstMeaningfulPaintCandidate`: When the browser first considers a meaningful paint might have occurred |
| | | - `firstMeaningfulPaint` (default): When the primary content of the page is visible |
| | | - `DOMContentLoaded`: When initial HTML is completely loaded and parsed |
| | | - `load`: When the whole page and all dependent resources (images, styles) are finished loading |
| | | - `networkIdle`: When there are no more than 0 network connections for at least 500ms |
| | | - `networkAlmostIdle`: When there are no more than 2 network connections for at least 500ms |
| `userAgent` | string | Custom User-Agent string for the request |
| `blockCookieDefault` | boolean | Whether to block cookies by default (default: true) |
| `blockFilter` | string | Custom filter rules using Adblock Plus / uBlock Origin syntax for blocking requests. See [filter syntax documentation](https://github.com/gorhill/uBlock/wiki/Static-filter-syntax) |
## Example Requests
### Basic Screenshot
```
/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=png&width=1920&height=1080
```
### Full Page JPEG Screenshot with Caching
```
/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=jpeg&width=1920&fullPage=true&quality=90&cache_ttl=3600
```
### Signed API Key Request
```
/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=png&width=1920&height=1080&cache_ttl=3600&signature=YOUR_GENERATED_SIGNATURE
```
## Response
The API returns:
- On success: The captured image or video file
- On error: An appropriate HTTP error status with error message
## Error Handling
The API will return appropriate HTTP status codes for different error scenarios:
- 400: Invalid parameters or missing required fields
- 401: Invalid API key or signature
- 403: Unauthorized access
- 404: Resource not found
- 500: Server errors
## Best Practices
1. Always URL-encode the target URL
2. Set appropriate viewport dimensions for your use case
3. Consider using `fullPage=true` for capturing long web pages
4. Adjust JPEG quality for better performance when high fidelity isn't required
5. Use appropriate `waitUntil` events based on your needs:
- `firstMeaningfulPaint` (default) for general captures
- `networkIdle` for dynamic content
- `load` for static content
6. Set custom `userAgent` when needed to handle specific site requirements
7. Enable caching with appropriate TTL for frequently accessed pages
8. Use signed API keys for enhanced security in production environments
## Need Help?
If you encounter any issues, have questions, or need additional features not covered here, please don't hesitate to reach out to our support team at support@scrnify.com. We're here to help!