ScrapeRequestDto

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hydrafetch-com/json-schema/hydrafetch-com-scrape-request-dto-schema.json",
  "title": "ScrapeRequestDto",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hydrafetch-com-openapi.json#/components/schemas/ScrapeRequestDto",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to scrape. Must be http(s); a bare domain such as example.com is read over https."
    },
    "maxAge": {
      "type": "number",
      "minimum": 0,
      "maximum": 604800000,
      "description": "Serve from cache if a capture of this URL is younger than this many milliseconds. Omit for the default 24h window; 0 always fetches fresh. Capped at 7 days."
    },
    "cacheOnly": {
      "type": "boolean",
      "description": "Only serve from cache. If there is no fresh cached copy, return 404 instead of fetching."
    },
    "storeInCache": {
      "type": "boolean",
      "description": "Persist the capture for later re-extraction. Default true."
    },
    "preferStructure": {
      "type": "boolean",
      "description": "Preserve document structure (headings, lists, tables) over prose density — good for marketing and service pages. Default off."
    },
    "async": {
      "type": "boolean",
      "description": "Return a job id immediately instead of waiting for the result. Poll GET /v1/web/scrape/{id}. Opt in only: a synchronous call never degrades to a job id on its own, so you get a page or an error, not two response shapes."
    },
    "onlyMainContent": {
      "type": "boolean",
      "description": "Return only the main content, dropping nav/boilerplate. Default true."
    },
    "includeTags": {
      "maxItems": 50,
      "description": "CSS selectors to keep. When set, only matching elements are considered.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "excludeTags": {
      "maxItems": 50,
      "description": "CSS selectors to strip before extraction.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "removeBase64Images": {
      "type": "boolean",
      "description": "Strip inline base64 images from the output. Default true."
    },
    "blockAds": {
      "type": "boolean",
      "description": "Remove common ad and tracking elements. Default true."
    },
    "includeLinks": {
      "type": "boolean",
      "description": "Keep inline links in the markdown. By default links are kept wherever the page text carries them. Set true to keep them on every page, or false for the densest prose."
    },
    "waitFor": {
      "type": "number",
      "minimum": 0,
      "maximum": 30000,
      "description": "Extra milliseconds to let the page settle before capture."
    },
    "timeout": {
      "type": "number",
      "minimum": 1000,
      "maximum": 100000,
      "description": "Overall time budget for the request, in milliseconds."
    },
    "location": {
      "$ref": "#/$defs/LocationDto"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Extra request headers to send when fetching the page."
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST"
      ],
      "default": "GET",
      "description": "HTTP method to fetch the URL with. Use POST for endpoints that only answer a POST, such as JSON and GraphQL APIs. Defaults to GET."
    },
    "body": {
      "type": "string",
      "maxLength": 65536,
      "description": "Request body, sent verbatim. Only used when `method` is POST. Set the content type yourself via `headers`; nothing is assumed about the format."
    },
    "formats": {
      "type": "array",
      "description": "What to return. Omit for Markdown only. `structured` is the page's own data (no LLM, cheapest); `summary` and `json` are LLM-backed and cost more.",
      "items": {
        "type": "string",
        "enum": [
          "markdown",
          "html",
          "rawHtml",
          "links",
          "structured",
          "summary",
          "json",
          "brand"
        ]
      }
    },
    "jsonOptions": {
      "description": "Schema and/or prompt for the `json` format. One is required when `json` is requested.",
      "allOf": [
        {
          "$ref": "#/$defs/JsonOptionsDto"
        }
      ]
    }
  },
  "required": [
    "url"
  ],
  "$defs": {
    "JsonOptionsDto": {
      "type": "object",
      "properties": {
        "schema": {
          "type": "object",
          "additionalProperties": true,
          "description": "JSON Schema describing the shape you want the `json` format to return."
        },
        "prompt": {
          "type": "string",
          "maxLength": 2000,
          "description": "Natural-language instruction for the `json` format. Use with or instead of a schema."
        }
      }
    },
    "LocationDto": {
      "type": "object",
      "properties": {
        "country": {
          "type": "string",
          "description": "ISO 3166 alpha-2 country to fetch the page as if from."
        },
        "languages": {
          "description": "Preferred content languages, most-preferred first.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}