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