APIFreaks - API Hub for Developers Screenshot APIs API

openapi: 3.2.0
info:
  title: Apifreaks Api Hub For Developers Screenshot APIs API
  version: 1.0.0
  contact:
    name: APIFreaks Support
    url: https://apifreaks.com/contact
    email: support@apifreaks.com
  description: 'Operations tagged Screenshot APIs across 2 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-screenshot-openapi.json, apifreaks-api-hub-for-developers-website-screenshot-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
  description: Bulk Screenshot API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: Screenshot APIs
paths:
  /screenshot:
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: Bulk Screenshot API Server
    post:
      tags:
      - Screenshot APIs
      summary: Capture screenshots of multiple websites in a single request.
      description: "Our Bulk Screenshot API allows you to capture screenshots of multiple webpages simultaneously, saving you time and effort. Instead of manually capturing each page one by one, you can batch process URLs and receive high-quality screenshots in the format you choose.\n Maximum `50 URLs` per request."
      operationId: bulkScreenshot
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          default: json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkScreenshotRequest'
            examples:
              typicalRequest:
                summary: Typical bulk screenshot request
                value:
                  urls:
                  - url: https://example.com
                    file_type: PNG
                  - url: https://github.com
                    file_type: JPEG
                    full_page: true
      responses:
        '200':
          description: Successful response. Each item in `results` corresponds to one requested URL, in the same order; a URL that fails validation or capture returns an error object in its `url` field instead of screenshot data, while `status` stays "fulfilled" and `error_message` stays null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkScreenshotResponse'
              examples:
                success:
                  summary: Successful response with mixed results
                  value:
                    status: success
                    meta_data:
                      total_urls: 2
                      successful_urls: 1
                      failed_urls: 1
                    results:
                    - url:
                        screenshot: https://s3.eu-central-2.wasabisys.com/w.storage.apifreaks.com/example_com_6d83e1744f01.png
                        url: https://example.com
                        created_at: '2026-07-27T10:18:31.378Z'
                        file_type: PNG
                        output: json
                        ttl: '2026-08-26T10:18:28.034Z'
                        sizes: null
                      status: fulfilled
                      error_message: null
                    - url:
                        timestamp: '2026-07-27T10:18:28.872Z'
                        status: 400
                        error: invalid_url
                        message: Your URL is incorrect
                        path: /v3/screenshot
                      status: fulfilled
                      error_message: null
        '400':
          description: Invalid request body
          content:
            application/json:
              examples:
                InvalidBody:
                  summary: Invalid request body
                  value:
                    error: Invalid request body Exception
                    message: Please provide data in required format in request body
                    path: /v1.0/screenshot
                    status: 400
                    timestamp: '2026-07-27T10:18:42.036Z'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large
          content:
            application/json:
              examples:
                PayloadTooLarge:
                  summary: Payload too large
                  value:
                    error: Payload too large Exception
                    message: Maximum request body size limit exceeded
                    path: /v1.0/screenshot
                    status: 413
                    timestamp: '2026-07-27T10:18:57.172Z'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Screenshot APIs
      summary: Build screenshots the way real users see the web — not just what fits on the screen.
      description: 'Capture full-page screenshots and videos of websites with advanced options like device simulation, custom code injection, cookie banner blocking, and scrollable content recording.

        Supports multiple output formats including JSON, image, GIF, MP4, and WebM.

        '
      operationId: websiteScreenshot
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          default: json
        description: 'Response format: ''json''.'
      - name: output
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - image
        description: Output format for screenshot results
      - name: file_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - PNG
          - JPEG
          - WEBP
          - PDF
          - mp4
          - gif
          - webm
        description: File type for screenshot output
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: URLs to capture screenshots of
      - name: width
        in: query
        required: false
        schema:
          type: integer
        description: Browser viewport width in pixels
      - name: height
        in: query
        required: false
        schema:
          type: integer
        description: Browser viewport height in pixels
      - name: full_page
        in: query
        required: false
        schema:
          type: boolean
        description: Capture a full-page screenshot
      - name: fresh
        in: query
        required: false
        schema:
          type: boolean
        description: Bypass cache and take a fresh screenshot
      - name: no_cookie_banners
        in: query
        required: false
        schema:
          type: boolean
        description: Remove cookie banners from the screenshot
      - name: enable_caching
        in: query
        required: false
        schema:
          type: boolean
        description: Enable caching for repeated requests
      - name: block_ads
        in: query
        required: false
        schema:
          type: boolean
        description: Block advertisements on the page
      - name: block_chat_widgets
        in: query
        required: false
        schema:
          type: boolean
        description: Block chat widget scripts from loading
      - name: extract_text
        in: query
        required: false
        schema:
          type: boolean
        description: Extract visible text from the page
      - name: extract_html
        in: query
        required: false
        schema:
          type: boolean
        description: Extract HTML content of the page
      - name: destroy_screenshot
        in: query
        required: false
        schema:
          type: boolean
        description: Auto-destroy screenshot after fetch
      - name: lazy_load
        in: query
        required: false
        schema:
          type: boolean
        description: Enable lazy-loading content before screenshot
      - name: retina
        in: query
        required: false
        schema:
          type: boolean
        description: Capture screenshot in high-DPI (Retina) mode
      - name: dark_mode
        in: query
        required: false
        schema:
          type: boolean
        description: Render page in dark mode
      - name: block_tracking
        in: query
        required: false
        schema:
          type: boolean
        description: Block common user-tracking scripts
      - name: enable_incognito
        in: query
        required: false
        schema:
          type: boolean
        description: Enable private/incognito mode for browser session
      - name: omit_background
        in: query
        required: false
        schema:
          type: boolean
        description: Omit background color (transparent background)
      - name: thumbnail_width
        in: query
        required: false
        schema:
          type: integer
        description: Thumbnail width in pixels
      - name: adjust_top
        in: query
        required: false
        schema:
          type: integer
        description: Adjust top in pixels
      - name: wait_for_event
        in: query
        required: false
        schema:
          type: string
          enum:
          - load
          - domcontentloaded
          - networkidle
        description: Wait for a specific load event before capturing the screenshot.
      - name: grayscale
        in: query
        required: false
        schema:
          type: integer
        description: Range:0 to 100 for grayscale filter
      - name: delay
        in: query
        required: false
        schema:
          type: integer
        description: How many milliseconds to wait before taking the screenshot
      - name: timeout
        in: query
        required: false
        schema:
          type: integer
        description: Maximum timeout in milliseconds. Defalut is `10,000`
      - name: ttl
        in: query
        required: false
        schema:
          type: integer
        description: Number of seconds the screenshot should be cached
      - name: clip[x]
        in: query
        required: false
        schema:
          type: integer
        description: X position of the clipping rectangle in pixels
      - name: clip[y]
        in: query
        required: false
        schema:
          type: integer
        description: Y position of the clipping rectangle in pixels
      - name: clip[width]
        in: query
        required: false
        schema:
          type: integer
        description: Width of the clipping rectangle in pixels
      - name: clip[height]
        in: query
        required: false
        schema:
          type: integer
        description: Height of the clipping rectangle in pixels
      - name: css_url
        in: query
        required: false
        schema:
          type: string
        description: URL to CSS file
      - name: css
        in: query
        required: false
        schema:
          type: string
        description: Your custom CSS code
      - name: js_url
        in: query
        required: false
        schema:
          type: string
        description: URL to JS file
      - name: js
        in: query
        required: false
        schema:
          type: string
        description: Your JS code
      - name: block_js
        in: query
        required: false
        schema:
          type: boolean
        description: Block Scripts
      - name: block_stylesheets
        in: query
        required: false
        schema:
          type: boolean
        description: Block Stylesheets
      - name: block_images
        in: query
        required: false
        schema:
          type: boolean
        description: Block Images
      - name: block_media
        in: query
        required: false
        schema:
          type: boolean
        description: Block Media
      - name: block_font
        in: query
        required: false
        schema:
          type: boolean
        description: Block Fonts
      - name: block_text_track
        in: query
        required: false
        schema:
          type: boolean
        description: Block Text Tracks
      - name: block_xhr
        in: query
        required: false
        schema:
          type: boolean
        description: Block XHR Requests
      - name: block_fetch
        in: query
        required: false
        schema:
          type: boolean
        description: Block Fetch Requests
      - name: block_event_source
        in: query
        required: false
        schema:
          type: boolean
        description: Block Event Source
      - name: block_web_socket
        in: query
        required: false
        schema:
          type: boolean
        description: Block Web Sockets
      - name: block_manifest
        in: query
        required: false
        schema:
          type: boolean
        description: Block Manifest
      - name: block_specific_requests
        in: query
        required: false
        schema:
          type: string
        description: 'Comma- or newline-separated list of specific requests to block. Each line and comma are treated as separate requests for processing. Example: https://example.com, https://example.js'
      - name: blur_selector
        in: query
        required: false
        style: form
        explode: false
        schema:
          type: string
        description: 'Comma-separated list of indexed CSS selectors to blur. Format: index:<selector>, e.g., 0:.banner,1:#ads.'
      - name: remove_selector
        in: query
        required: false
        style: form
        explode: false
        schema:
          type: string
        description: 'Comma-separated list of indexed CSS selectors to remove. Format: index:<selector>, e.g., 0:.banner,1:#ads.'
      - name: result_file_name
        in: query
        required: false
        schema:
          type: string
        description: Specify a meaningful and unique file name to easily identify the screenshot result. Avoid using spaces or special characters; use hyphens or underscores to separate words.
      - name: scrolling_screenshot
        in: query
        required: false
        schema:
          type: boolean
        description: '**`Scrolling Screenshot`**: Capture a long scrolling screenshot. When true, disable `fullPage` and `freshScreenshot`.'
      - name: scroll_speed
        in: query
        required: false
        schema:
          type: string
          enum:
          - normal
          - fast
          - slow
        description: Speed of scrolling during the screenshot.
      - name: scroll_back
        in: query
        required: false
        schema:
          type: boolean
        description: If true, the scroll will reverse back to the top after reaching the bottom.
      - name: start_immediately
        in: query
        required: false
        schema:
          type: boolean
        description: If true, the scrolling capture will start immediately upon page load.
      - name: multiple_scrolling
        in: query
        required: false
        schema:
          type: boolean
        description: If true, multiple scrolling screenshots will be taken at different viewport sizes.
      - name: sizes
        in: query
        required: false
        style: form
        explode: false
        schema:
          type: string
        description: 'Comma-separated list of viewport sizes in format index:XXw:YYh. Example: sizes=0:120w:300h,1:240w:500h'
      - name: duration
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 60
        description: Duration in seconds for the scrolling capture. Acceptable range is 0 to 60 seconds.
      - name: fail_on_error
        in: query
        required: false
        schema:
          type: boolean
        description: If true, returns an error when the target page responds with 4xx or 5xx status.
      - name: longitude
        in: query
        required: false
        schema:
          type: number
        description: Specify longitude for the browser Geolocation API.
      - name: latitude
        in: query
        required: false
        schema:
          type: number
        description: Specify latitude for the browser Geolocation API.
      - name: proxy
        in: query
        required: false
        schema:
          type: string
        description: 'Allows defining a proxy for the connection. Provide a JSON string with keys: server (include port number), username, and password.'
      - name: headers
        in: query
        required: false
        schema:
          type: string
        description: Custom HTTP headers to include as key=value pairs. Use a semicolon to separate multiple headers (e.g., key1=value1;key2=value2).
      - name: cookies
        in: query
        required: false
        schema:
          type: string
        description: 'Cookies to include in the request before rendering. Supports single or multiple cookies. Example: cookie=value; otherCookie=otherValue;'
      - name: scroll_to_element
        in: query
        required: false
        schema:
          type: string
        description: Scrolls the page to bring the specified CSS selector into view before capture.
      - name: selector
        in: query
        required: false
        schema:
          type: string
        description: CSS selector to capture a specific element. Only that element is rendered.
      - name: selector_to_click
        in: query
        required: false
        schema:
          type: string
        description: CSS selector for an element to click before capturing the screenshot.
      - name: click_recursion
        in: query
        required: false
        schema:
          type: integer
        description: 'Number of times to click the selector (when set via selector_to_click). Default: 1.'
      - name: user_agent
        in: query
        required: false
        schema:
          type: string
        description: Custom User-Agent string sent in the request headers.
      - name: accept_languages
        in: query
        required: false
        schema:
          type: string
        description: Sets the accepted languages for the HTTP request. Sent as the Accept-Language header.
      - name: scroll_delay
        in: query
        required: false
        schema:
          type: integer
        description: Delay in milliseconds between scroll steps when lazy_load is enabled.
      - name: custom_html
        in: query
        required: false
        schema:
          type: string
        description: Custom HTML to render instead of loading a URL. Overrides the url option.
      - name: image_quality
        in: query
        required: false
        schema:
          type: integer
        description: Compression level for JPEG output (0–100). Lower = smaller file, higher = better quality. Only applies to JPEG.
      - name: extract_markdown
        in: query
        required: false
        schema:
          type: boolean
        description: Extracts rendered page content as a structured .md (Markdown) file.
      - name: get_image_urls
        in: query
        required: false
        schema:
          type: boolean
        description: Extracts all image URLs from the rendered DOM and returns them in structured format.
      responses:
        '200':
          description: Successful PDF response
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenshotResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    screenshot: https://s3.eu-central-2.wasabisys.com/w.storage.apifreaks.com/example_com_e56fe7e60d8d.png
                    url: https://example.com
                    created_at: '2026-07-27T10:19:08.668Z'
                    format: json
                    ttl: '2026-08-26T10:19:05.486Z'
        '400':
          description: Bad Request — Invalid or missing parameters
          content:
            application/json:
              examples:
                InvalidUrl:
                  summary: Invalid URL
                  value:
                    timestamp: '2026-07-27T10:19:11.354Z'
                    status: 400
                    error: invalid_url
                    message: Your URL is incorrect
                    path: /v3/screenshot
                missingUrl:
                  summary: Missing required url parameter
                  value:
                    error: Invalid Param Exception
                    message: please pass correct parameters
                    path: /v1.0/screenshot
                    status: 400
                    timestamp: '2026-07-27T10:19:11.922Z'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request Timeout — Screenshot capture exceeded the configured timeout
          content:
            application/json:
              examples:
                RequestTimeout:
                  summary: Request timed out
                  value:
                    timestamp: '2026-07-27T10:19:25.676Z'
                    status: 408
                    error: timeout_error
                    message: The request took too long to complete. Please try again later.
                    path: /v3/screenshot
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BulkScreenshotSuccessItem:
      type: object
      description: Per-URL result entry. The `url` field holds either the screenshot metadata or an error object, depending on whether that specific URL was captured successfully.
      required:
      - status
      - url
      properties:
        status:
          type: string
          description: Processing status for this item (fulfilled).
        url:
          description: Screenshot metadata for this URL, or an error object if this specific URL could not be captured.
          oneOf:
          - description: Screenshot metadata with the same structure as the single Website Screenshot API response.
            $ref: '#/components/schemas/BulkScreenshotUrlData'
          - description: Per-item error returned when this specific URL cannot be captured.
            $ref: '#/components/schemas/ErrorResponse'
        error_message:
          type:
          - string
          - 'null'
          description: Observed to always be null; per-item error details are returned inside `url` instead.
    BulkScreenshotMetaData:
      type: object
      description: Metadata about the bulk screenshot request results.
      required:
      - total_urls
      - successful_urls
      - failed_urls
      properties:
        total_urls:
          type: integer
          description: Total number of URLs processed.
        successful_urls:
          type: integer
          description: Number of URLs successfully processed.
        failed_urls:
          type: integer
          description: Number of URLs that failed to process.
    ClipRect:
      type: object
      description: Clipping rectangle dimensions for the captured area.
      required:
      - x
      - y
      - width
      - height
      properties:
        x:
          type: integer
          description: X position of the clip rectangle in pixels.
        y:
          type: integer
          description: Y position of the clip rectangle in pixels.
        width:
          type: integer
          description: Width of the clip rectangle in pixels.
        height:
          type: integer
          description: Height of the clip rectangle in pixels.
    BulkScreenshotUrlData:
      type: object
      description: Screenshot result data for a single URL. Contains the same fields as the single Website Screenshot API response.
      required:
      - screenshot
      - url
      - created_at
      properties:
        screenshot:
          type: string
          format: uri
          description: URL of the captured screenshot image.
        url:
          type: string
          format: uri
          description: The original URL that was captured.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the screenshot was created (ISO 8601 format).
        format:
          type: string
          description: Response format type.
        ttl:
          type: string
          description: Time until the screenshot expires (ISO 8601 format).
        file_type:
          type: string
          description: The file type of the output.
        extracted_html:
          type: string
          format: uri
          description: URL of the extracted HTML from the webpage.
        extracted_text:
          type: string
          format: uri
          description: URL of the extracted plain text from the webpage.
        enable_caching:
          type: boolean
          description: Whether caching was enabled.
        omit_background:
          type: boolean
          description: Whether background was removed.
        destroy_screenshot:
          type: boolean
          description: Whether the screenshot was destroyed after generation.
        fail_on_error:
          type: boolean
          description: Whether the request failed on error.
        longitude:
          type: number
          format: float
          description: The longitude value used for geolocation.
        latitude:
          type: number
          format: float
          description: The latitude value used for geolocation.
        proxy:
          type: string
          description: The proxy configuration used.
        no_cookie_banners:
          type: boolean
          description: Whether cookie banners were blocked.
        block_ads:
          type: boolean
          description: Whether ads were blocked.
        headers:
          type: string
          description: Custom headers included in the request.
        cookies:
          type: string
          description: Cookies included in the request.
        scroll_to_element:
          type: string
          description: Element scrolled to before rendering.
        selector:
          type: string
          description: Element selected for rendering.
        blur_selector:
          type: string
          description: Elements blurred in the output.
        remove_selector:
          type: string
          description: Elements removed from the output.
        css:
          type: string
          description: Custom CSS injected into the page.
        css_url:
          type: string
          format: uri
          description: External CSS URL that was loaded.
        js:
          type: string
          description: Custom JavaScript that was injected.
        js_url:
          type: string
          format: uri
          description: External JavaScript URL that was loaded.
        user_agent:
          type: string
          description: User-Agent string that was used.
        accept_languages:
          type: string
          description: Accept-Language header that was used.
        delay:
          type: integer
          description: Delay duration in milliseconds.
        thumbnail_width:
          type: integer
          description: Thumbnail width in pixels.
        output:
          type: string
          description: Output type used.
        fresh:
          type: boolean
          description: Whether a fresh render was performed.
        lazy_load:
          type: boolean
          description: Whether lazy loading was triggered.
        full_page:
          type: boolean
          description: Whether full page capture was used.
        retina:
          type: boolean
          description: Whether retina capture was used.
        height:
          type: integer
          description: Viewport height used in pixels.
        width:
          type: integer
          description: Viewport width used in pixels.
        custom_html:
          type: string
          description: Custom HTML content rendered.
        block_chat_widgets:
          type: boolean
          description: Whether chat widgets were blocked.
        block_js:
          type: boolean
          description: Whether JavaScript was blocked.
        block_stylesheets:
          type: boolean
          description: Whether stylesheets were blocked.
        block_images:
          type: boolean
          description: Whether images were blocked.
        block_media:
          type: boolean
          description: Whether media files were blocked.
        block_font:
          type: boolean
          description: Whether fonts were blocked.
        block_text_track:
          type: boolean
          description: Whether text tracks were blocked.
        block_xhr:
          type: boolean
          description: Whether XHR requests were blocked.
        block_fetch:
          type: boolean
          description: Whether Fetch API requests were blocked.
        block_event_source:
          type: boolean
          description: Whether EventSource connections were blocked.
        block_web_socket:
          type: boolean
          description: Whether WebSocket connections were blocked.
        block_manifest:
          type: boolean
          description: Whether manifest files were blocked.
        block_specific_requests:
          type: string
          description: Specific requests that were blocked.
        adjust_top:
          type: integer
          description: Vertical position scrolled to in pixels.
        image_quality:
          type: integer
          description: Image quality level applied.
        extract_html:
          type: boolean
          description: Whether HTML content was extracted.
        extract_text:
          type: boolean
          description: Whether text content was extracted.
        dark_mode:
          type: boolean
          description: Whether dark mode was enabled.
        block_tracking:
          type: boolean
          description: Whether tracking scripts were blocked.
        wait_for_event:
          type: string
          description: The event that triggered rendering.
        grayscale:
          type: integer
          description: Grayscale level applied (0-100).
        clip:
          $ref: '#/components/schemas/ClipRect'
        result_file_name:
          type: string
          description: Final filename used for the output.
        enable_incognito:
          type: boolean
          description: Whether incognito mode was enabled.
        timeout:
          type: integer
          description: Actual timeout duration in milliseconds.
        scrolling_screenshot:
          type: boolean
          description: Whether scrolling screenshot mode was enabled.
        multiple_scrolling:
          type: boolean
          description: Whether multiple scrolling captures were performed.
        sizes:
          type: array
          items:
            type: string
          description: Dimensions used for each capture.
        extract_markdown:
          type: boolean
          description: Whether markdown extraction was enabled.
        get_image_urls:
          type: boolean
          description: Whether image URL extraction was enabled.
        scroll_delay:
          type: integer
          description: Delay between scroll steps in milliseconds.
        selector_to_click:
          type: string
          description: CSS selector clicked before capture.
        click_recursion:
          type: integer
          description: Number of times the selector was clicked.
        video:
          type: boolean
          description: Whether viewport recording mode was enabled.
    ScreenshotResponse:
      type: object
      description: Website screenshot response containing the screenshot URL and metadata.
      required:
      - screenshot
      - url
      - created_at
      - format
      - ttl
      properties:
        screenshot:
          type: string
          format: uri
          description: URL of the captured screenshot image file.
        url:
          type: string
          format: uri
          description: The original URL that was captured.
        created_at:
      

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apifreaks-api-hub-for-developers/refs/heads/main/openapi/apifreaks-api-hub-for-developers-screenshot-apis-api-openapi.yml