SearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/deepsfetch-com/json-schema/deepsfetch-com-search-request-schema.json",
  "title": "SearchRequest",
  "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/SearchRequest",
  "allOf": [
    {
      "$ref": "#/$defs/CommonOptions"
    },
    {
      "type": "object",
      "required": [
        "query"
      ],
      "properties": {
        "query": {
          "type": "string"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 10
        },
        "scrapeResults": {
          "type": "boolean",
          "enum": [
            false
          ],
          "description": "Use /v2/scrape separately. Combined search and scraping is not supported."
        },
        "source": {
          "enum": [
            "web",
            "news",
            "images"
          ],
          "default": "web",
          "description": "Web pages, news articles or images. One provider request per search."
        },
        "category": {
          "enum": [
            "general",
            "developer",
            "research"
          ],
          "default": "general",
          "description": "Domain allowlist for Web results; use general with News or Images. No additional DeepSFetch credits."
        },
        "sources": {
          "type": "array",
          "minItems": 1,
          "maxItems": 5,
          "uniqueItems": true,
          "items": {
            "enum": [
              "web",
              "news",
              "images",
              "developer",
              "research"
            ]
          },
          "description": "Combine Web, News, Images, Developer and Research. Developer and Research use domain filters without additional DeepSFetch credits."
        }
      }
    }
  ],
  "$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."
    }
  }
}