ScreenshotRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ironfang/main/json-schema/ironfang-screenshot-request-schema.json",
  "title": "ScreenshotRequest",
  "x-generated": "2026-09-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ironfang-render-api-openapi.yml#/components/schemas/ScreenshotRequest",
  "allOf": [
    {
      "$ref": "#/$defs/RenderCommon"
    },
    {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Page to capture. Mutually exclusive with `html`."
        },
        "html": {
          "type": "string",
          "description": "Markup to render. Mutually exclusive with `url`."
        },
        "width": {
          "type": "integer",
          "default": 1280,
          "maximum": 4096,
          "description": "Viewport width in pixels."
        },
        "height": {
          "type": "integer",
          "default": 800,
          "maximum": 4096,
          "description": "Viewport height. Ignored when `full_page` is set."
        },
        "full_page": {
          "type": "boolean",
          "default": false,
          "description": "Capture the whole scrollable page."
        },
        "selector": {
          "type": "string",
          "description": "CSS selector of a single element to capture instead of the\nviewport.\n"
        },
        "clip": {
          "$ref": "#/$defs/Clip"
        },
        "omit_background": {
          "type": "boolean",
          "default": false,
          "description": "Transparent background instead of the page's own. Ignored for\n`jpeg`, which has no alpha channel.\n"
        },
        "full_page_max_height": {
          "type": "integer",
          "default": 20000,
          "maximum": 20000,
          "description": "Cap a `full_page` capture at this many pixels. An\ninfinite-scroll page has no natural end, so 20000 applies when\nnone is given, and is also the most that can be asked for.\n"
        },
        "dark_mode": {
          "type": "boolean",
          "default": false,
          "description": "Render with `prefers-color-scheme: dark`."
        },
        "format": {
          "type": "string",
          "enum": [
            "png",
            "jpeg",
            "webp"
          ],
          "default": "png",
          "description": "PNG is lossless and the default. WebP is typically a fraction of\nthe size for the same picture, which is what matters when the\noutput is served to browsers or social crawlers.\n"
        },
        "quality": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 85,
          "description": "Quality for the lossy formats, `jpeg` and `webp`. Ignored for PNG."
        },
        "device": {
          "type": "string",
          "enum": [
            "desktop",
            "tablet",
            "mobile"
          ],
          "description": "Capture as a phone or tablet rather than a desktop window that\nhappens to be narrow. Sets the viewport, the device pixel ratio,\ntouch, and a matching mobile user agent together - width alone\ngets media queries right and everything else wrong.\n\nAn explicit `width` or `height` still wins, so a preset can be\nused for the density and user agent while overriding the size.\n"
        },
        "delay_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000,
          "description": "Extra settle time after load. Renderwolf watches the page and\ncaptures when it stops changing, so this is rarely needed - use\nit for content that arrives on a timer, which quiescence cannot\nanticipate. Capped at ten seconds.\n"
        }
      }
    }
  ],
  "$defs": {
    "Clip": {
      "type": "object",
      "description": "A rectangle in CSS pixels from the top left of the page.",
      "required": [
        "width",
        "height"
      ],
      "properties": {
        "x": {
          "type": "number",
          "default": 0
        },
        "y": {
          "type": "number",
          "default": 0
        },
        "width": {
          "type": "number",
          "maximum": 4096
        },
        "height": {
          "type": "number",
          "maximum": 4096
        }
      }
    },
    "Cookie": {
      "type": "object",
      "required": [
        "name",
        "domain"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "value": {
          "type": "string"
        },
        "domain": {
          "type": "string",
          "description": "Required. Chromium silently drops a domainless cookie set before\nnavigation, so the render would quietly come back logged out.\n"
        },
        "path": {
          "type": "string",
          "default": "/"
        }
      }
    },
    "RenderCommon": {
      "type": "object",
      "properties": {
        "no_cache": {
          "type": "boolean",
          "default": false,
          "description": "Force a fresh render instead of serving a cached one. Always\nbillable. Excluded from the cache key, so repeated fresh requests\ndo not collide.\n"
        },
        "block_ads": {
          "type": "boolean",
          "default": false,
          "description": "Drop requests to known ad and tracker networks before they load.\nStopped as network requests rather than hidden afterwards, so the\npage never spends time fetching them.\n"
        },
        "block_cookie_banners": {
          "type": "boolean",
          "default": false,
          "description": "Hide common consent banners, and undo the scroll lock they set -\nwithout which a full-page capture is one viewport tall.\n\nHidden, not accepted. Clicking \"accept\" would be a decision made\non the site owner's behalf and recorded as theirs.\n"
        },
        "hide_selectors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "CSS selectors to hide before capturing. Applied after load, so\nelements injected by script are covered.\n"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Extra HTTP headers sent with every request for the page."
        },
        "cookies": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Cookie"
          },
          "description": "Cookies to set before navigating. Set beforehand because a session\ncookie that arrives after load has missed the request it was meant\nto authenticate.\n"
        },
        "authorization": {
          "type": "string",
          "description": "Sets the `Authorization` header - the common case, spelled once.\nAn explicit `Authorization` in `headers` wins over this.\n"
        },
        "user_agent": {
          "type": "string",
          "description": "Overrides the user agent, including any set by `device`.\n"
        },
        "wait_until": {
          "type": "string",
          "enum": [
            "load",
            "domcontentloaded",
            "networkidle"
          ],
          "default": "load",
          "description": "When the page counts as ready. `networkidle` waits for traffic to\nstop and is bounded by the render timeout, because a page with\npolling never truly idles.\n"
        },
        "wait_for_selector": {
          "type": "string",
          "description": "Wait for this element before capturing. Fails the render if it\nnever appears, rather than returning a half-drawn page.\n"
        },
        "timeout_ms": {
          "type": "integer",
          "description": "Per-render timeout. Clamped to the service maximum - it can lower\nthe ceiling but not raise it.\n"
        },
        "device_scale_factor": {
          "type": "number",
          "minimum": 1,
          "maximum": 3,
          "description": "Pixel density. 2 is retina: the same CSS size at twice the pixels.\n"
        }
      }
    }
  }
}