# 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
<pre>
<code>{process.env.NEXT_PUBLIC_API_URL}capture</code>
</pre>

## 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!