{ "openapi": "3.0.3", "info": { "title": "Screenshotty - Website Screenshot API", "description": "A powerful screenshot API that captures high-quality screenshots of websites or raw HTML content. Supports various output formats, custom viewports, JavaScript/CSS injection, element selection, geo-targeting, and more.\n\n## Quick Start\n\nGet your API key from the dashboard and start capturing screenshots:\n```bash\ncurl -X GET \"https://api.screenshotty.link/api/v1/screenshot?url=https://example.com\" \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\n## Features\n- Capture full-page or viewport screenshots\n- Multiple output formats (PNG, JPEG, WebP, PDF, etc.)\n- Custom viewport dimensions (up to 4K resolution)\n- Crop specific regions or capture specific CSS selectors\n- JavaScript and CSS injection for page manipulation\n- Cookie and HTTP header support for authenticated pages\n- Geo-targeting with proxy support from multiple countries\n- Built-in ad blocker\n- Fast processing with real browser rendering\n\n## Rate Limits\nRate limits depend on your subscription plan. Check your dashboard for details.", "version": "1.1.0" }, "servers": [ { "url": "https://api.screenshotty.link", "description": "Production Server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v1/screenshot": { "get": { "summary": "Take a screenshot (GET)", "description": "Capture a screenshot of a URL or HTML content using query parameters. This endpoint is useful for simple requests or when you need to embed the screenshot URL directly in HTML (e.g., ``).\n\n**Tip**: For GET requests, all options must be passed as query parameters.", "operationId": "getScreenshot", "tags": ["Screenshot"], "x-code-samples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X GET \"https://api.screenshotty.link/api/v1/screenshot?url=https%3A%2F%2Fexample.com&format=image%2Fpng\" \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n --output screenshot.png" }, { "lang": "JavaScript", "label": "Node.js (axios)", "source": "const axios = require('axios');\nconst fs = require('fs');\n\nconst options = {\n method: 'GET',\n url: 'https://api.screenshotty.link/api/v1/screenshot',\n params: {\n url: 'https://example.com',\n format: 'image/png'\n },\n headers: {\n 'x-api-key': 'YOUR_API_KEY'\n },\n responseType: 'arraybuffer'\n};\n\naxios.request(options)\n .then(response => fs.writeFileSync('screenshot.png', response.data))\n .catch(error => console.error(error));" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nurl = \"https://api.screenshotty.link/api/v1/screenshot\"\n\nparams = {\n \"url\": \"https://example.com\",\n \"format\": \"image/png\"\n}\n\nheaders = {\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(url, headers=headers, params=params)\n\nwith open(\"screenshot.png\", \"wb\") as f:\n f.write(response.content)" }, { "lang": "PHP", "label": "PHP (cURL)", "source": " \"https://api.screenshotty.link/api/v1/screenshot?url=https%3A%2F%2Fexample.com&format=image%2Fpng\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n \"x-api-key: YOUR_API_KEY\"\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\nfile_put_contents('screenshot.png', $response);" } ], "parameters": [ { "$ref": "#/components/parameters/url" }, { "$ref": "#/components/parameters/html" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/response_type" }, { "$ref": "#/components/parameters/viewport_width" }, { "$ref": "#/components/parameters/viewport_height" }, { "$ref": "#/components/parameters/crop_x" }, { "$ref": "#/components/parameters/crop_y" }, { "$ref": "#/components/parameters/crop_width" }, { "$ref": "#/components/parameters/crop_height" }, { "$ref": "#/components/parameters/selector" }, { "$ref": "#/components/parameters/full_page" }, { "$ref": "#/components/parameters/transparent_background" }, { "$ref": "#/components/parameters/ready_event" }, { "$ref": "#/components/parameters/wait_ms" }, { "$ref": "#/components/parameters/javascript_code" }, { "$ref": "#/components/parameters/css_code" }, { "$ref": "#/components/parameters/user_agent" }, { "$ref": "#/components/parameters/http_headers" }, { "$ref": "#/components/parameters/adblock" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/block_cookie_banner" }, { "$ref": "#/components/parameters/light_mode" }, { "$ref": "#/components/parameters/viewport_preset" }, { "$ref": "#/components/parameters/device_scale_factor" }, { "$ref": "#/components/parameters/language" }, { "$ref": "#/components/parameters/scroll_to_bottom" }, { "$ref": "#/components/parameters/printed" }, { "$ref": "#/components/parameters/webhook_url" }, { "$ref": "#/components/parameters/webhook_method" } ], "responses": { "200": { "$ref": "#/components/responses/ScreenshotSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Take a screenshot (POST)", "description": "Capture a screenshot of a URL or HTML content. This endpoint is recommended for complex requests, especially when using cookies, HTTP headers, or JavaScript/CSS injection.\n\n**Flexible parameter passing**: All options can be passed either as query parameters (in the URL) or in the JSON request body — use whichever is more convenient for your use case. You can even mix both: parameters from the query string and body are merged, with body parameters taking precedence if the same option is specified in both places.", "operationId": "postScreenshot", "tags": ["Screenshot"], "x-code-samples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://api.screenshotty.link/api/v1/screenshot\" \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY\" \\\n -d '{\n \"url\": \"https://example.com\",\n \"format\": \"image/png\",\n \"viewport_width\": 1920,\n \"viewport_height\": 1080,\n \"full_page\": true\n }' \\\n --output screenshot.png" }, { "lang": "JavaScript", "label": "Node.js (axios)", "source": "const axios = require('axios');\nconst fs = require('fs');\n\nconst options = {\n method: 'POST',\n url: 'https://api.screenshotty.link/api/v1/screenshot',\n headers: {\n 'Content-Type': 'application/json',\n 'x-api-key': 'YOUR_API_KEY'\n },\n data: {\n url: 'https://example.com',\n format: 'image/png',\n viewport_width: 1920,\n viewport_height: 1080,\n full_page: true,\n javascript_code: \"document.querySelector('.cookie-banner')?.remove();\"\n },\n responseType: 'arraybuffer'\n};\n\naxios.request(options)\n .then(response => fs.writeFileSync('screenshot.png', response.data))\n .catch(error => console.error(error));" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nurl = \"https://api.screenshotty.link/api/v1/screenshot\"\n\npayload = {\n \"url\": \"https://example.com\",\n \"format\": \"image/png\",\n \"viewport_width\": 1920,\n \"viewport_height\": 1080,\n \"full_page\": True,\n \"javascript_code\": \"document.querySelector('.cookie-banner')?.remove();\"\n}\n\nheaders = {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.post(url, json=payload, headers=headers)\n\nwith open(\"screenshot.png\", \"wb\") as f:\n f.write(response.content)" }, { "lang": "PHP", "label": "PHP (cURL)", "source": " \"https://api.screenshotty.link/api/v1/screenshot\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => json_encode([\n 'url' => 'https://example.com',\n 'format' => 'image/png',\n 'viewport_width' => 1920,\n 'viewport_height' => 1080,\n 'full_page' => true\n ]),\n CURLOPT_HTTPHEADER => [\n \"Content-Type: application/json\",\n \"x-api-key: YOUR_API_KEY\"\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\nfile_put_contents('screenshot.png', $response);" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenshotRequest" }, "examples": { "simpleUrl": { "summary": "Simple URL screenshot", "value": { "url": "https://example.com", "format": "image/png" } }, "customViewport": { "summary": "Custom viewport size", "value": { "url": "https://example.com", "viewport_width": 1440, "viewport_height": 900, "format": "image/webp" } }, "withJavaScript": { "summary": "With JavaScript injection", "value": { "url": "https://example.com", "javascript_code": "document.querySelector('.cookie-banner')?.remove();", "ready_event": "networkidle", "wait_ms": 1000 } }, "htmlContent": { "summary": "Screenshot raw HTML", "value": { "html": "

Hello World

", "viewport_width": 800, "viewport_height": 600 } }, "elementScreenshot": { "summary": "Screenshot a specific element", "value": { "url": "https://example.com", "selector": "#main-content", "transparent_background": true, "format": "image/png" } }, "withCookiesAndHeaders": { "summary": "With cookies and custom headers", "value": { "url": "https://example.com/dashboard", "cookies": [ { "name": "session_id", "value": "abc123", "domain": "example.com" } ], "http_headers": { "Authorization": "Bearer token123", "Accept-Language": "en-US" } } }, "pdfExport": { "summary": "Export as PDF", "value": { "url": "https://example.com/report", "format": "application/pdf", "full_page": true } }, "geoTargeted": { "summary": "Screenshot from specific country", "value": { "url": "https://example.com", "country": "US", "response_type": "json" } }, "mobileSimulation": { "summary": "Simulate mobile device", "description": "Capture a screenshot as it would appear on an iPhone", "value": { "url": "https://example.com", "viewport_width": 390, "viewport_height": 844, "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1", "format": "image/png" } }, "socialMediaCard": { "summary": "Generate social media preview card", "description": "Create an Open Graph / Twitter card sized image", "value": { "url": "https://example.com", "viewport_width": 1200, "viewport_height": 630, "full_page": false, "format": "image/png" } }, "printedPdf": { "summary": "Generate print-ready PDF", "description": "Create a PDF optimized for printing, using the browser's print mode", "value": { "url": "https://example.com/article", "printed": true, "full_page": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ScreenshotSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/screenshot/countries": { "get": { "summary": "List available countries", "description": "Returns a list of available country codes that can be used with the `country` parameter to take screenshots from different geographic locations using proxies.", "operationId": "listCountries", "tags": ["Screenshot"], "x-code-samples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X GET \"https://api.screenshotty.link/api/v1/screenshot/countries\" \\\n -H \"x-api-key: YOUR_API_KEY\"" }, { "lang": "JavaScript", "label": "Node.js (axios)", "source": "const axios = require('axios');\n\nconst options = {\n method: 'GET',\n url: 'https://api.screenshotty.link/api/v1/screenshot/countries',\n headers: {\n 'x-api-key': 'YOUR_API_KEY'\n }\n};\n\naxios.request(options)\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nurl = \"https://api.screenshotty.link/api/v1/screenshot/countries\"\n\nheaders = {\n \"x-api-key\": \"YOUR_API_KEY\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())" } ], "responses": { "200": { "description": "List of available country codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" }, "example": ["US", "UK", "DE", "FR", "JP", "BR"] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Screenshotty API key. Get this from your dashboard at https://screenshotty.link" } }, "parameters": { "url": { "name": "url", "in": "query", "description": "The URL of the webpage to capture. Either `url` or `html` must be provided, but not both.", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://example.com" } }, "html": { "name": "html", "in": "query", "description": "Raw HTML content to render and capture. Useful for generating images from dynamic content or templates. Either `url` or `html` must be provided, but not both.", "required": false, "schema": { "type": "string", "example": "

Hello World

" } }, "format": { "name": "format", "in": "query", "description": "The output image format. Defaults to `image/png`.", "required": false, "schema": { "type": "string", "enum": [ "image/png", "image/jpg", "image/jpeg", "image/gif", "image/webp", "image/jp2", "image/tiff", "application/pdf" ], "default": "image/png" } }, "response_type": { "name": "response_type", "in": "query", "description": "How the screenshot should be returned:\n- `image` (default): Returns the raw image binary data with appropriate Content-Type header\n- `file`: Same as `image`, returns raw binary data\n- `json`: Returns a JSON object with the image URL, image dimensions, and the raw HTML content of the page\n- `url`: Same as `json`, returns `{\"url\": \"...\", \"width\": 1280, \"height\": 800, \"mime\": \"image/png\", \"html\": \"...\"}`\n- `redirect`: Performs an HTTP redirect to the image URL", "required": false, "schema": { "type": "string", "enum": ["image", "json", "url", "redirect", "file"], "default": "image" } }, "viewport_width": { "name": "viewport_width", "in": "query", "description": "The width of the browser viewport in pixels. This determines the width of the rendered page. Maximum value is 3840 pixels.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3840, "default": 1920, "example": 1920 } }, "viewport_height": { "name": "viewport_height", "in": "query", "description": "The height of the browser viewport in pixels. This affects the visible area before scrolling. Maximum value is 3840 pixels. Note: If `full_page` is true, the screenshot will capture the entire scrollable content regardless of this value.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3840, "default": 1080, "example": 1080 } }, "crop_x": { "name": "crop_x", "in": "query", "description": "The X coordinate (in pixels) of the top-left corner of the crop region. Use together with `crop_y`, `crop_width`, and `crop_height` to capture a specific portion of the page.", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 100 } }, "crop_y": { "name": "crop_y", "in": "query", "description": "The Y coordinate (in pixels) of the top-left corner of the crop region. Use together with `crop_x`, `crop_width`, and `crop_height` to capture a specific portion of the page.", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 50 } }, "crop_width": { "name": "crop_width", "in": "query", "description": "The width (in pixels) of the crop region. Use together with `crop_x`, `crop_y`, and `crop_height` to capture a specific portion of the page.", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 800 } }, "crop_height": { "name": "crop_height", "in": "query", "description": "The height (in pixels) of the crop region. Use together with `crop_x`, `crop_y`, and `crop_width` to capture a specific portion of the page.", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 600 } }, "selector": { "name": "selector", "in": "query", "description": "A CSS selector to identify a specific element to screenshot. Only the matching element will be captured, ignoring the rest of the page. Useful for capturing specific components like charts, cards, or sections.", "required": false, "schema": { "type": "string", "example": "#main-content" } }, "full_page": { "name": "full_page", "in": "query", "description": "When `true`, captures the entire scrollable page content, not just the visible viewport. When `false`, only captures the visible viewport area.", "required": false, "schema": { "type": "boolean", "default": true } }, "transparent_background": { "name": "transparent_background", "in": "query", "description": "When `true`, makes the background transparent (only works with PNG format). Useful for capturing elements that you want to overlay on other images or backgrounds.", "required": false, "schema": { "type": "boolean", "default": false } }, "ready_event": { "name": "ready_event", "in": "query", "description": "Specifies when to consider the page ready for screenshot:\n- `load`: Wait for the `load` event (all resources loaded)\n- `domcontentloaded` (default): Wait for the `DOMContentLoaded` event (HTML parsed)\n- `networkidle`: Wait until there are no more than 2 network connections for 500ms\n- `networkidle2`: Same as `networkidle`\n- `networkidle0`: Wait until there are no network connections for 500ms", "required": false, "schema": { "type": "string", "enum": ["load", "domcontentloaded", "networkidle", "networkidle2", "networkidle0"], "default": "domcontentloaded" } }, "wait_ms": { "name": "wait_ms", "in": "query", "description": "Additional time to wait (in milliseconds) after the `ready_event` before taking the screenshot. Useful for pages with animations or delayed content loading.", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 1000 } }, "user_agent": { "name": "user_agent", "in": "query", "description": "Custom User-Agent string to use when loading the page. Useful for accessing mobile versions of sites or bypassing basic bot detection.", "required": false, "schema": { "type": "string", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15" } }, "adblock": { "name": "adblock", "in": "query", "description": "When `true`, blocks ads and trackers for a cleaner screenshot. This can also speed up page loading.", "required": false, "schema": { "type": "boolean", "default": false } }, "country": { "name": "country", "in": "query", "description": "Two-letter country code (ISO 3166-1 alpha-2) to take the screenshot from a specific geographic location using a proxy. Use the `/api/v1/screenshot/countries` endpoint to get the list of available countries.", "required": false, "schema": { "type": "string", "example": "US" } }, "http_headers": { "name": "http_headers", "in": "query", "description": "Custom HTTP headers to send with the request (JSON encoded). Useful for authentication, language preferences, or custom headers required by the target site.", "required": false, "schema": { "type": "string", "example": "{\"Authorization\": \"Bearer token123\", \"Accept-Language\": \"en-US\"}" } }, "javascript_code": { "name": "javascript_code", "in": "query", "description": "JavaScript code to execute on the page before taking the screenshot. Useful for removing popups, clicking buttons, scrolling, or modifying the page content.", "required": false, "schema": { "type": "string", "example": "document.querySelector('.cookie-banner')?.remove();" } }, "css_code": { "name": "css_code", "in": "query", "description": "CSS code to inject into the page before taking the screenshot. Useful for hiding elements, changing styles, or adding custom styling.", "required": false, "schema": { "type": "string", "example": ".advertisement { display: none !important; }" } }, "block_cookie_banner": { "name": "block_cookie_banner", "in": "query", "description": "When `true`, automatically detects and removes cookie consent banners and GDPR popups from the page before taking the screenshot.", "required": false, "schema": { "type": "boolean", "default": false } }, "light_mode": { "name": "light_mode", "in": "query", "description": "Controls the color scheme preference for the page:\n- `default`: Use the page's default color scheme\n- `light`: Force light mode (prefers-color-scheme: light)\n- `dark`: Force dark mode (prefers-color-scheme: dark)", "required": false, "schema": { "type": "string", "enum": ["default", "light", "dark"], "default": "default" } }, "viewport_preset": { "name": "viewport_preset", "in": "query", "description": "Quick viewport size preset for common devices. If specified, this sets both `viewport_width` and `viewport_height` automatically. You can still override individual dimensions by providing explicit `viewport_width` or `viewport_height` values.\n\nAvailable presets:\n- `desktop`: 1920×1080 (Full HD)\n- `desktop_hd`: 2560×1440 (2K/QHD)\n- `desktop_4k`: 3840×2160 (4K/UHD)\n- `tablet`: 768×1024 (iPad portrait)\n- `tablet_landscape`: 1024×768 (iPad landscape)\n- `mobile`: 390×844 (generic mobile portrait)\n- `mobile_landscape`: 844×390 (generic mobile landscape)\n- `mobile_android`: 360×800 (Android portrait)\n- `mobile_android_landscape`: 800×360 (Android landscape)\n- `iphone_se`: 375×667 (iPhone SE)\n- `iphone_14`: 390×844 (iPhone 14)\n- `iphone_14_pro`: 393×852 (iPhone 14 Pro)\n- `iphone_14_pro_max`: 430×932 (iPhone 14 Pro Max)\n- `iphone_15`: 393×852 (iPhone 15)\n- `iphone_15_pro_max`: 430×932 (iPhone 15 Pro Max)", "required": false, "schema": { "type": "string", "enum": ["desktop", "desktop_hd", "desktop_4k", "tablet", "tablet_landscape", "mobile", "mobile_landscape", "mobile_android", "mobile_android_landscape", "iphone_se", "iphone_14", "iphone_14_pro", "iphone_14_pro_max", "iphone_15", "iphone_15_pro_max"] } }, "device_scale_factor": { "name": "device_scale_factor", "in": "query", "description": "The device scale factor (pixel density) to use when rendering the page. A value of 2 simulates a Retina display, producing an image with twice the resolution. Useful for capturing high-DPI screenshots.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1, "example": 2 } }, "language": { "name": "language", "in": "query", "description": "The language code to set for the browser. This affects the `Accept-Language` header and the `navigator.language` property in JavaScript. Use standard language codes like `en-US`, `fr-FR`, `de-DE`, `ja-JP`, etc.", "required": false, "schema": { "type": "string", "default": "en-US", "example": "en-US" } }, "scroll_to_bottom": { "name": "scroll_to_bottom", "in": "query", "description": "When `true`, scrolls the page to the bottom before taking the screenshot. This is useful for triggering lazy-loaded content, animations, and ensuring all dynamic elements are loaded.", "required": false, "schema": { "type": "boolean", "default": false } }, "printed": { "name": "printed", "in": "query", "description": "When `true`, generates a print-ready PDF version of the page (as if using the browser's print dialog). This option forces the output format to `application/pdf`. The resulting PDF is optimized for printing, respecting print stylesheets (@media print) and removing screen-only elements.", "required": false, "schema": { "type": "boolean", "default": false } }, "webhook_url": { "name": "webhook_url", "in": "query", "description": "URL to receive a webhook notification when the screenshot is completed or fails.", "required": false, "schema": { "type": "string", "format": "uri" } }, "webhook_method": { "name": "webhook_method", "in": "query", "description": "HTTP method to use when sending the webhook notification.", "required": false, "schema": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH"], "default": "POST" } } }, "schemas": { "ScreenshotRequest": { "type": "object", "description": "Request body for creating a screenshot via POST. **Tip**: All these options can also be passed as query parameters in the URL — use whichever method is more convenient. If the same parameter is provided in both the query string and the request body, the body value takes precedence.", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL of the webpage to capture. Either `url` or `html` must be provided, but not both.", "example": "https://example.com" }, "html": { "type": "string", "description": "Raw HTML content to render and capture. Useful for generating images from dynamic content or templates. Either `url` or `html` must be provided, but not both.", "example": "

Hello World

" }, "format": { "type": "string", "description": "The output image format. Defaults to `image/png`.", "enum": [ "image/png", "image/jpg", "image/jpeg", "image/gif", "image/webp", "image/jp2", "image/tiff", "application/pdf" ], "default": "image/png" }, "response_type": { "type": "string", "description": "How the screenshot should be returned:\n- `image` (default): Returns the raw image binary data with appropriate Content-Type header\n- `file`: Same as `image`, returns raw binary data\n- `json`: Returns a JSON object with the image URL, image dimensions, and the raw HTML content of the page\n- `url`: Same as `json`, returns `{\"url\": \"...\", \"width\": 1280, \"height\": 800, \"mime\": \"image/png\", \"html\": \"...\"}`\n- `redirect`: Performs an HTTP redirect to the image URL", "enum": ["image", "json", "url", "redirect", "file"], "default": "image" }, "viewport_width": { "type": "integer", "description": "The width of the browser viewport in pixels. Maximum value is 3840 pixels.", "minimum": 1, "maximum": 3840, "default": 1920, "example": 1920 }, "viewport_height": { "type": "integer", "description": "The height of the browser viewport in pixels. Maximum value is 3840 pixels.", "minimum": 1, "maximum": 3840, "default": 1080, "example": 1080 }, "crop_x": { "type": "integer", "description": "The X coordinate (in pixels) of the top-left corner of the crop region.", "minimum": 0, "example": 100 }, "crop_y": { "type": "integer", "description": "The Y coordinate (in pixels) of the top-left corner of the crop region.", "minimum": 0, "example": 50 }, "crop_width": { "type": "integer", "description": "The width (in pixels) of the crop region.", "minimum": 1, "example": 800 }, "crop_height": { "type": "integer", "description": "The height (in pixels) of the crop region.", "minimum": 1, "example": 600 }, "selector": { "type": "string", "description": "A CSS selector to identify a specific element to screenshot. Only the matching element will be captured.", "example": "#main-content" }, "full_page": { "type": "boolean", "description": "When `true`, captures the entire scrollable page content.", "default": true }, "transparent_background": { "type": "boolean", "description": "When `true`, makes the background transparent (only works with PNG format).", "default": false }, "ready_event": { "type": "string", "description": "Specifies when to consider the page ready for screenshot:\n- `load`: Wait for the `load` event (all resources loaded)\n- `domcontentloaded` (default): Wait for the `DOMContentLoaded` event (HTML parsed)\n- `networkidle`: Wait until there are no more than 2 network connections for 500ms\n- `networkidle2`: Same as `networkidle`\n- `networkidle0`: Wait until there are no network connections for 500ms", "enum": ["load", "domcontentloaded", "networkidle", "networkidle2", "networkidle0"], "default": "domcontentloaded" }, "wait_ms": { "type": "integer", "description": "Additional time to wait (in milliseconds) after the `ready_event` before taking the screenshot.", "minimum": 0, "example": 1000 }, "javascript_code": { "type": "string", "description": "JavaScript code to execute on the page before taking the screenshot. Useful for removing popups, clicking buttons, scrolling, or modifying the page content.", "example": "document.querySelector('.cookie-banner')?.remove();" }, "css_code": { "type": "string", "description": "CSS code to inject into the page before taking the screenshot. Useful for hiding elements, changing styles, or adding custom styling.", "example": ".advertisement { display: none !important; }" }, "user_agent": { "type": "string", "description": "Custom User-Agent string to use when loading the page.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15" }, "cookies": { "type": "array", "description": "Array of cookies to set before loading the page. Useful for authenticated sessions or personalized content.", "items": { "$ref": "#/components/schemas/Cookie" }, "example": [ { "name": "session_id", "value": "abc123", "domain": "example.com" } ] }, "http_headers": { "type": "object", "description": "Custom HTTP headers to send with the request. Useful for authentication, language preferences, or custom headers required by the target site.", "additionalProperties": { "type": "string" }, "example": { "Authorization": "Bearer token123", "Accept-Language": "en-US" } }, "adblock": { "type": "boolean", "description": "When `true`, blocks ads and trackers for a cleaner screenshot.", "default": false }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2) to take the screenshot from a specific geographic location.", "example": "US" }, "block_cookie_banner": { "type": "boolean", "description": "When `true`, automatically detects and removes cookie consent banners and GDPR popups from the page before taking the screenshot.", "default": false }, "light_mode": { "type": "string", "description": "Controls the color scheme preference for the page:\n- `default`: Use the page's default color scheme\n- `light`: Force light mode (prefers-color-scheme: light)\n- `dark`: Force dark mode (prefers-color-scheme: dark)", "enum": ["default", "light", "dark"], "default": "default" }, "viewport_preset": { "type": "string", "description": "Quick viewport size preset for common devices. If specified, this sets both `viewport_width` and `viewport_height` automatically. You can still override individual dimensions.\n\nAvailable presets:\n- `desktop`: 1920×1080 (Full HD)\n- `desktop_hd`: 2560×1440 (2K/QHD)\n- `desktop_4k`: 3840×2160 (4K/UHD)\n- `tablet`: 768×1024 (iPad portrait)\n- `tablet_landscape`: 1024×768 (iPad landscape)\n- `mobile`: 390×844 (generic mobile portrait)\n- `mobile_landscape`: 844×390 (generic mobile landscape)\n- `mobile_android`: 360×800 (Android portrait)\n- `mobile_android_landscape`: 800×360 (Android landscape)\n- `iphone_se`: 375×667 (iPhone SE)\n- `iphone_14`: 390×844 (iPhone 14)\n- `iphone_14_pro`: 393×852 (iPhone 14 Pro)\n- `iphone_14_pro_max`: 430×932 (iPhone 14 Pro Max)\n- `iphone_15`: 393×852 (iPhone 15)\n- `iphone_15_pro_max`: 430×932 (iPhone 15 Pro Max)", "enum": ["desktop", "desktop_hd", "desktop_4k", "tablet", "tablet_landscape", "mobile", "mobile_landscape", "mobile_android", "mobile_android_landscape", "iphone_se", "iphone_14", "iphone_14_pro", "iphone_14_pro_max", "iphone_15", "iphone_15_pro_max"] }, "device_scale_factor": { "type": "integer", "description": "The device scale factor (pixel density) to use when rendering the page. A value of 2 simulates a Retina display, producing an image with twice the resolution. Useful for capturing high-DPI screenshots.", "minimum": 1, "maximum": 3, "default": 1, "example": 2 }, "language": { "type": "string", "description": "The language code to set for the browser. This affects the `Accept-Language` header and the `navigator.language` property in JavaScript. Use standard language codes like `en-US`, `fr-FR`, `de-DE`, `ja-JP`, etc.", "default": "en-US", "example": "en-US" }, "scroll_to_bottom": { "type": "boolean", "description": "When `true`, scrolls the page to the bottom before taking the screenshot. This is useful for triggering lazy-loaded content, animations, and ensuring all dynamic elements are loaded.", "default": false }, "printed": { "type": "boolean", "description": "When `true`, generates a print-ready PDF version of the page (as if using the browser's print dialog). This option forces the output format to `application/pdf`. The resulting PDF is optimized for printing, respecting print stylesheets (@media print) and removing screen-only elements.", "default": false }, "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive a webhook notification when the screenshot is completed or fails. The webhook will be sent as an HTTP request with a JSON payload containing the screenshot details and result.", "example": "https://your-server.com/webhooks/screenshot" }, "webhook_method": { "type": "string", "description": "HTTP method to use when sending the webhook notification.", "enum": ["GET", "POST", "PUT", "PATCH"], "default": "POST" }, "webhook_headers": { "type": "object", "description": "Custom HTTP headers to include in the webhook request. Useful for authentication or custom routing.", "additionalProperties": { "type": "string" }, "example": { "Authorization": "Bearer your-webhook-secret", "X-Custom-Header": "custom-value" } } } }, "Cookie": { "type": "object", "description": "A browser cookie to set before loading the page", "required": ["name", "value"], "properties": { "name": { "type": "string", "description": "The name of the cookie", "example": "session_id" }, "value": { "type": "string", "description": "The value of the cookie", "example": "abc123xyz" }, "domain": { "type": "string", "description": "The domain for which the cookie is valid. If not specified, defaults to the URL's domain.", "example": "example.com" }, "path": { "type": "string", "description": "The path for which the cookie is valid", "default": "/", "example": "/" }, "expires": { "type": "number", "description": "Unix timestamp (in seconds) when the cookie expires", "example": 1735689600 }, "httpOnly": { "type": "boolean", "description": "Whether the cookie is HTTP-only", "default": false }, "secure": { "type": "boolean", "description": "Whether the cookie should only be sent over HTTPS", "default": false }, "sameSite": { "type": "string", "description": "The SameSite attribute of the cookie", "enum": ["Strict", "Lax", "None"] } } }, "ScreenshotUrlResponse": { "type": "object", "description": "Response when `response_type` is `json` or `url`", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL where the screenshot image can be accessed", "example": "https://screenshots.screenshotty.link/abc123.png" }, "html": { "type": "string", "description": "The raw HTML content of the loaded page. Contains the full HTML source as rendered by the browser.", "example": "Example..." } } }, "ErrorResponse": { "type": "object", "description": "Error response returned when the request fails", "properties": { "error": { "type": "string", "description": "A human-readable error message describing what went wrong", "example": "Country 'XX' is not available. Available countries: US, UK, DE, FR" } } }, "RapidAPIErrorResponse": { "type": "object", "description": "Error response from RapidAPI (subscription, quota, or rate limit issues)", "properties": { "message": { "type": "string", "description": "A human-readable error message from RapidAPI", "example": "You have exceeded the MONTHLY quota for requests on your current plan." } } } }, "responses": { "ScreenshotSuccess": { "description": "Screenshot captured successfully. The response format depends on the `responseType` parameter:\n- `image`/`file`: Returns binary image data\n- `json`/`url`: Returns JSON with image URL\n- `redirect`: Returns 302 redirect to image URL", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScreenshotUrlResponse" } } } }, "BadRequest": { "description": "Bad request - Invalid parameters or screenshot processing failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidCountry": { "summary": "Invalid country code", "value": { "error": "Country 'XX' is not available. Available countries: US, UK, DE, FR" } }, "processingFailed": { "summary": "Screenshot processing failed", "value": { "error": "Navigation timeout: page took too long to load" } } } } } }, "Unauthorized": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Invalid or missing API key" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Screenshot processing failed: no image URL returned" } } } }, "Forbidden": { "description": "Forbidden - Subscription inactive or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RapidAPIErrorResponse" }, "examples": { "subscriptionInactive": { "summary": "Subscription not active", "value": { "message": "You are not subscribed to this API." } }, "quotaExceeded": { "summary": "Monthly quota exceeded", "value": { "message": "You have exceeded the MONTHLY quota for requests on your current plan." } } } } } }, "TooManyRequests": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RapidAPIErrorResponse" }, "example": { "message": "You have exceeded the rate limit per second for your plan. Please upgrade your plan or wait before making more requests." } } }, "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests allowed per time window", "schema": { "type": "integer", "example": 100 } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current time window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit resets", "schema": { "type": "integer", "example": 1702598400 } } } } } }, "tags": [ { "name": "Screenshot", "description": "Endpoints for capturing screenshots of webpages and HTML content", "x-displayName": "Screenshot" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true, "samples-languages": ["curl", "node", "python", "php", "java", "csharp", "go", "ruby"] } }