PdfRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ironfang/main/json-schema/ironfang-pdf-request-schema.json",
  "title": "PdfRequest",
  "x-generated": "2026-09-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ironfang-render-api-openapi.yml#/components/schemas/PdfRequest",
  "allOf": [
    {
      "$ref": "#/$defs/RenderCommon"
    },
    {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Page to print. Mutually exclusive with `html`."
        },
        "html": {
          "type": "string",
          "description": "Markup to print. Mutually exclusive with `url`."
        },
        "landscape": {
          "type": "boolean",
          "default": false
        },
        "paper_format": {
          "type": "string",
          "enum": [
            "a3",
            "a4",
            "a5",
            "letter",
            "legal",
            "tabloid"
          ],
          "description": "Named page size. Omit for Chromium's default, which is Letter.\nSizes are portrait; `landscape` rotates them.\n"
        },
        "margin": {
          "$ref": "#/$defs/Margin"
        },
        "print_background": {
          "type": "boolean",
          "default": false,
          "description": "Include background colours and images. Off by default, matching\na browser's print dialog.\n"
        },
        "header_html": {
          "type": "string",
          "description": "Chromium print header template."
        },
        "footer_html": {
          "type": "string",
          "description": "Chromium print footer template."
        },
        "scale": {
          "type": "number",
          "description": "Print scale. Omit or `0` for 1.0."
        }
      }
    }
  ],
  "$defs": {
    "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": "/"
        }
      }
    },
    "Margin": {
      "type": "object",
      "description": "Page margins in inches. Omitted sides keep Chromium's default rather\nthan becoming zero - a PDF printed hard to the paper edge is rarely\nwhat leaving a field out was meant to mean.\n",
      "properties": {
        "top": {
          "type": "number"
        },
        "right": {
          "type": "number"
        },
        "bottom": {
          "type": "number"
        },
        "left": {
          "type": "number"
        }
      }
    },
    "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"
        }
      }
    }
  }
}