ScrapeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/deepsfetch-com/json-schema/deepsfetch-com-scrape-request-schema.json",
  "title": "ScrapeRequest",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/deepsfetch-com-api-openapi.json#/components/schemas/ScrapeRequest",
  "allOf": [
    {
      "$ref": "#/$defs/CommonOptions"
    },
    {
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "formats": {
          "type": "array",
          "items": {
            "enum": [
              "markdown",
              "html",
              "links",
              "screenshot",
              "json"
            ]
          },
          "description": "Use html/markdown on the HTML path. render or screenshot routes to browser runtime supporting html/markdown/links/screenshot. json is a legacy accepted value without implemented JSON extraction."
        },
        "jsonSchema": {
          "type": "object",
          "deprecated": true,
          "description": "Legacy field; structured JSON generation is not implemented by the current scrape adapter/runtime. Use extract or validated templates."
        },
        "plannedLane": {
          "enum": [
            "http_basic",
            "cf_browser",
            "unlocker_http",
            "managed_browser"
          ],
          "default": "http_basic"
        },
        "timeoutMs": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 60000,
          "default": 30000
        },
        "waitUntil": {
          "enum": [
            "domcontentloaded",
            "load",
            "networkidle0",
            "networkidle2"
          ],
          "default": "domcontentloaded"
        },
        "fullPage": {
          "type": "boolean",
          "default": true
        },
        "collectionEngine": {
          "enum": [
            "auto",
            "premium"
          ],
          "description": "Opt in to the independent 1-credit engine. Basic and browser retries included. Premium requires a prior failed offer and explicit 12-credit approval."
        },
        "engineStrategy": {
          "enum": [
            "auto",
            "basic",
            "enhanced"
          ],
          "default": "auto"
        },
        "premiumSourceJobId": {
          "type": "string"
        },
        "premiumConsent": {
          "type": "object",
          "required": [
            "credits"
          ],
          "properties": {
            "credits": {
              "const": 12
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "CommonOptions": {
      "type": "object",
      "properties": {
        "async": {
          "type": "boolean",
          "default": false
        },
        "webhook": {
          "$ref": "#/$defs/Webhook"
        },
        "geo": {
          "type": "object",
          "properties": {
            "country": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "language": {
              "type": "string"
            }
          },
          "deprecated": true,
          "description": "Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution."
        },
        "session": {
          "type": "object",
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "ttlSeconds": {
              "type": "integer",
              "minimum": 60,
              "maximum": 86400
            }
          },
          "deprecated": true,
          "description": "Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution."
        },
        "device": {
          "enum": [
            "desktop",
            "mobile",
            "tablet"
          ],
          "deprecated": true,
          "description": "Legacy common option. Not forwarded by the HTML adapter or recognized by the current browser runtime. Do not rely on it to customize execution."
        },
        "render": {
          "oneOf": [
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "properties": {
                "waitMs": {
                  "type": "integer"
                },
                "waitFor": {
                  "type": "string"
                },
                "timeoutMs": {
                  "type": "integer"
                }
              }
            }
          ],
          "description": "For scrape, true or an object selects browser runtime. Nested wait/timeout settings are not runtime settings: use top-level timeoutMs and waitUntil. Browser runtime does not support credit caps."
        },
        "costControl": {
          "type": "object",
          "properties": {
            "maxCredits": {
              "type": "integer",
              "minimum": 0,
              "description": "Additional task credit cap. External AI provider costs are excluded.",
              "maximum": 1000000000
            },
            "cacheMode": {
              "enum": [
                "fresh",
                "prefer"
              ]
            },
            "maxAgeSeconds": {
              "type": "integer",
              "minimum": 0,
              "maximum": 86400
            },
            "allowFallback": {
              "type": "boolean",
              "description": "Set false to restrict fallback. General estimation includes fallback unless false; quickstart forces false."
            },
            "taskId": {
              "type": "string",
              "description": "Shared task budget identifier within the workspace. Use a new ID per logical run; distinct from idempotency.",
              "minLength": 1,
              "maxLength": 160,
              "pattern": "^[a-zA-Z0-9:_-]+$"
            }
          },
          "description": "Supported on compatible scrape/map/crawl/extract, independent collection engine and current search paths. Legacy browser runtime/interact and V2 watch creation reject credit caps. External AI costs excluded."
        }
      }
    },
    "Webhook": {
      "type": "object",
      "required": [
        "url",
        "secret"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "secret": {
          "type": "string",
          "minLength": 16
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Accepted configuration metadata is not included in the current delivered event payload."
        }
      },
      "description": "See https://deepsfetch.com/docs/webhooks for HMAC verification and delivery limitations. No automatic webhook retry in the current delivery chain."
    }
  }
}