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

https://api.scrnify.com/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):

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

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!