Website Screenshot (by Domain or URL)

{
  "type": "object",
  "anyOf": [
    {
      "required": [
        "domain"
      ]
    },
    {
      "required": [
        "directUrl"
      ]
    }
  ],
  "properties": {
    "page": {
      "enum": [
        "login",
        "signup",
        "blog",
        "careers",
        "pricing",
        "terms",
        "privacy",
        "contact"
      ],
      "type": "string",
      "description": "Capture a specific page TYPE instead of the landing page: the upstream service crawls the domain's links and picks the best match (30 languages supported). Only valid with domain."
    },
    "domain": {
      "type": "string",
      "minLength": 3,
      "description": "Domain to screenshot, e.g. 'example.com'. Mutually exclusive with directUrl."
    },
    "country": {
      "type": "string",
      "maxLength": 2,
      "minLength": 2,
      "description": "Two-letter ISO 3166-1 alpha-2 country code (e.g. 'us', 'gb', 'de'). Must be one of the supported countries."
    },
    "maxAgeMs": {
      "type": "integer",
      "default": 86400000,
      "maximum": 2592000000,
      "minimum": 0,
      "description": "Reuse a cached result younger than this many milliseconds. Default 86400000 (1 day), max 2592000000 (30 days). Set 0 to always fetch fresh."
    },
    "directUrl": {
      "type": "string",
      "format": "uri",
      "description": "Exact URL to use, bypassing domain resolution (e.g. 'https://example.com/pricing'). Mutually exclusive with domain."
    },
    "timeoutMS": {
      "type": "integer",
      "maximum": 300000,
      "minimum": 1000,
      "description": "Upstream timeout in milliseconds (max 300000). The upstream service aborts the call with a 408 when exceeded. Keep it below the endpoint's requestTimeoutMs so the provider answers before the platform's own budget expires."
    },
    "waitForMs": {
      "type": "integer",
      "maximum": 30000,
      "minimum": 0,
      "description": "Extra browser wait in milliseconds after page load before the content is captured (0-30000). Useful for JavaScript-heavy pages."
    },
    "colorScheme": {
      "enum": [
        "light",
        "dark"
      ],
      "type": "string",
      "description": "Browser color scheme to emulate for sites that honor prefers-color-scheme."
    },
    "scrollOffset": {
      "type": "integer",
      "maximum": 100000,
      "minimum": 0,
      "description": "Vertical scroll offset in pixels: returns the viewport-sized slice starting at this Y offset, so a long page can be walked in chunks. Takes precedence over fullScreenshot."
    },
    "fullScreenshot": {
      "type": "boolean",
      "default": false,
      "description": "Capture the entire page instead of a single viewport. Default false."
    },
    "handleCookiePopup": {
      "type": "boolean",
      "default": false,
      "description": "Dismiss the cookie/consent banner before capturing. Default false."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "code": {
      "type": [
        "number",
        "string"
      ],
      "description": "200 (an HTTP-style status code) on a successful capture; a string such as 'HTTP_400' on an upstream error."
    },
    "width": {
      "type": "number",
      "description": "Capture width in pixels."
    },
    "domain": {
      "type": "string",
      "description": "Echoes the requested domain."
    },
    "height": {
      "type": "number",
      "description": "Capture height in pixels."
    },
    "status": {
      "type": "string",
      "description": "'ok' on the one successful capture observed."
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message, present only on an upstream error (e.g. a domain that does not resolve)."
    },
    "screenshot": {
      "type": "string",
      "description": "URL of the rendered screenshot image, hosted on the upstream vendor's own CDN (media.brand.dev) -- not the aggregator's own host and not a customer's private data, so it ships through as captured."
    },
    "cache_metadata": {
      "type": "object",
      "properties": {
        "age_ms": {
          "type": "number",
          "description": "Age of the cached result in milliseconds. 0 on a fresh (miss) fetch."
        },
        "status": {
          "type": "string",
          "description": "'miss' observed on the one successful capture; a repeat call within maxAgeMs is expected to read 'hit', unconfirmed."
        }
      },
      "description": "Whether this result was served from cache and, if so, how old it is.",
      "additionalProperties": true
    },
    "screenshotType": {
      "type": "string",
      "description": "'viewport' observed on the one successful capture (fullScreenshot was not requested); expected to read something like 'full' when fullScreenshot: true is passed, unconfirmed."
    }
  },
  "description": "A capture result (status/domain/dimensions/capture metadata) on a successful screenshot, or an error code/message when the domain does not resolve or the request is malformed.",
  "additionalProperties": true
}