ExtractRequestDto

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hydrafetch-com/json-schema/hydrafetch-com-extract-request-dto-schema.json",
  "title": "ExtractRequestDto",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hydrafetch-com-openapi.json#/components/schemas/ExtractRequestDto",
  "type": "object",
  "properties": {
    "urls": {
      "maxItems": 10,
      "description": "The pages to extract from. Each must be an http(s) URL. A trailing `/*` marks a crawl scope: every page discovered under that path is extracted and merged into the result.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "schema": {
      "type": "object",
      "additionalProperties": true,
      "description": "JSON Schema describing the shape you want back. Optional if `prompt` is given; when both are present the schema fixes the field names and types while the prompt guides what to pull."
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "description": "Natural-language instruction for what to extract. Use with or instead of a schema."
    },
    "preferStructure": {
      "type": "boolean",
      "description": "Preserve document structure (headings, lists, tables) over prose density when reading the page — good for listing and catalog pages. Default off."
    },
    "enableWebSearch": {
      "type": "boolean",
      "description": "Pull in extra source pages by web-searching your prompt, to fill fields your URLs do not cover. Requires a `prompt`."
    },
    "showSources": {
      "type": "boolean",
      "description": "Return the concrete list of URLs that were actually extracted, after any wildcard and web-search expansion. Default off."
    },
    "showConfidence": {
      "type": "boolean",
      "description": "For each field, return a confidence score and the exact source passage the value was drawn from. Default off."
    },
    "mergeEntities": {
      "type": "boolean",
      "description": "Merge the per-page results into one deduplicated collection — one row per entity, with its contributing source URLs — instead of a separate result per page. Default off."
    },
    "maxAge": {
      "type": "number",
      "minimum": 0,
      "maximum": 604800000,
      "description": "Reuse a recent capture of each page if it is younger than this many milliseconds. Omit or 0 to always fetch fresh. Capped at 7 days."
    },
    "location": {
      "description": "Fetch each page as if from this country and with these preferred languages, for sites that change prices or content by region.",
      "allOf": [
        {
          "$ref": "#/$defs/LocationDto"
        }
      ]
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Extra request headers to send when fetching each page, such as a cookie that picks the store or delivery area a site prices by."
    }
  },
  "required": [
    "urls"
  ],
  "$defs": {
    "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"
          }
        }
      }
    }
  }
}