{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/codai-ro/json-schema/codai-ro-tool-search-request-schema.json",
  "title": "Search request",
  "description": "Body of `POST /v1/tools/search`.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/codai-ro-gateway-openapi.yml#/components/schemas/ToolSearchRequest",
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 400,
      "description": "Search phrase (trimmed)."
    },
    "max_results": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5,
      "description": "Maximum number of results."
    },
    "freshness": {
      "type": "string",
      "enum": [
        "day",
        "week",
        "month",
        "year"
      ],
      "description": "Only pages published within the window; pages without a known publish date are dropped."
    },
    "include_domains": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "maxLength": 253
      },
      "description": "Only return pages from these hosts (subdomains included, optional path prefix such as `github.com/vercel`). Scheme and `www.` are stripped."
    },
    "exclude_domains": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "maxLength": 253
      },
      "description": "Never return pages from these hosts (same matching as `include_domains`)."
    },
    "published_after": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$",
      "description": "Only pages published on or after this date (`YYYY-MM-DD` or `YYYY-MM`); undated pages are dropped."
    },
    "published_before": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$",
      "description": "Only pages published before this date (`YYYY-MM-DD` or `YYYY-MM`); undated pages are dropped."
    },
    "content_chars": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2000,
      "description": "Also return a verified excerpt of up to this many characters per result in `content` (omitted or 0 = snippet only)."
    },
    "country": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "Two-letter market code. Omit it to let the gateway infer it from the query (`ro` for Romanian queries, `us` otherwise)."
    },
    "lang": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}(-[a-zA-Z]{2})?$",
      "description": "Language code, optionally with region (`en-US`). Omit it to infer it from the query; a `lang:xx` operator in the query wins."
    },
    "mode": {
      "type": "string",
      "enum": [
        "codai",
        "google",
        "fast",
        "deep"
      ],
      "default": "codai",
      "description": "`codai` (default): verified-only native search (`ToolSearchResponse`). `google`: Grounding with Google\nSearch on Vertex AI, returned as a separate `ToolSearchGoogleResponse` and never mixed with codai results;\n404 when the gateway has not enabled it, 503 `search_unavailable` when Google returns no grounding.\n`fast` / `deep` mean `codai` with that `depth` (alias kept for clients that send codai-search's own field).\n"
    },
    "depth": {
      "type": "string",
      "enum": [
        "fast",
        "deep"
      ],
      "default": "fast",
      "description": "codai-search depth. `fast` (default): ~4.5 s budget. `deep`: more sources and a ~12 s budget, for\nresearch, literature and comparison queries; with `fallback: auto` the whole request may take ~20 s.\n"
    },
    "fallback": {
      "type": "string",
      "enum": [
        "auto",
        "off"
      ],
      "default": "auto",
      "description": "With `mode: codai`: `auto` (default) attaches a separate `google` block (Grounding with Google Search)\nwhen codai's own results are weak (none, fewer than 3, or low coverage for code/docs/general/academic/education)\nor the search service is down; never for currency/weather/fuel/inflation/local_poi. `off` disables it.\n"
    }
  }
}