ScreenshotRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vee3-io/json-schema/vee3-io-screenshot-request-schema.json",
  "title": "ScreenshotRequest",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vee3-io-openapi.json#/components/schemas/ScreenshotRequest",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "title": "Url",
      "description": "Public http or https URL to capture. Private, localhost, and internal network addresses are blocked."
    },
    "full_page": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Full Page",
      "description": "Capture the full scrollable page. When false, only the viewport area is captured.",
      "default": false
    },
    "viewport_width": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 3840.0,
          "minimum": 320.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Viewport Width",
      "description": "Browser viewport width in pixels.",
      "default": 1280
    },
    "viewport_height": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 2160.0,
          "minimum": 240.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Viewport Height",
      "description": "Browser viewport height in pixels.",
      "default": 720
    },
    "wait_until": {
      "type": "string",
      "enum": [
        "load",
        "domcontentloaded",
        "networkidle"
      ],
      "title": "Wait Until",
      "description": "When to take the screenshot: 'load' (load event), 'domcontentloaded' (DOM ready, faster; use with post_load_wait to let the page settle), or 'networkidle' (no network activity for 500ms; can time out on pages with ongoing requests).",
      "default": "domcontentloaded"
    },
    "timeout_seconds": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 60.0,
          "minimum": 5.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Timeout Seconds",
      "description": "Maximum seconds to wait for the page to load before failing.",
      "default": 30
    },
    "post_load_wait": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 20.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Post Load Wait",
      "description": "Extra seconds to wait after wait_until before capturing. Only valid when wait_until is domcontentloaded. Use this instead of networkidle when pages keep network activity.",
      "default": 0
    },
    "format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ],
      "title": "Format",
      "description": "Output image format. 'png' preserves lossless quality (default). 'jpeg' produces smaller files.",
      "default": "png"
    },
    "quality": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Quality",
      "description": "JPEG compression quality from 0 (smallest) to 100 (best). Only applies when format is 'jpeg'; ignored for PNG.",
      "default": 80
    },
    "dark_mode": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Dark Mode",
      "description": "When true, emulate prefers-color-scheme: dark so sites with dark-mode CSS render in dark mode. Has no effect on sites without dark-mode styling.",
      "default": false
    },
    "block_cookie_banners": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Block Cookie Banners",
      "description": "When true, attempt to dismiss common cookie consent banners and overlays before capture. Best-effort - custom or first-party banners may remain.",
      "default": false
    },
    "file_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 255
        },
        {
          "type": "null"
        }
      ],
      "title": "File Name",
      "description": "Optional account-relative storage path for the screenshot. If omitted, the file is stored under downloads/ with a generated name."
    }
  },
  "type": "object",
  "required": [
    "url"
  ]
}