Web Tools

Add a web tool to a request and the router runs the searches and page fetches the model asks for, using the Web Search API and Contents API. The model sees the results with citation numbers and writes its answer. The response lists every source in web_results.

Tool Types

Declare these in tools on /v1/chat/completions.

A request can declare one web_search and one web_extract. A duplicate returns 400.

curl https://api.you.com/v1/chat/completions \
  -H "Authorization: Bearer $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "What changed in the latest Python release?"}],
    "tools": [
      {"type": "web_search", "freshness": "month", "count": 5},
      {"type": "web_extract", "formats": ["markdown"]}
    ]
  }'

web_search Parameters

All fields are optional and sit flat on the tool object. A value you set overrides the same parameter when the model supplies one. Search parameters match the Web Search API.

Other fields return 400. Each search times out after 15 seconds.

web_extract Parameters

The model chooses the URLs. You set how pages are fetched.

The router fetches at most 5 distinct http or https URLs per call and bills each extracted page. A fetch times out after 30 seconds.

Response

When a web tool runs, the response carries a web_results object next to choices. Citation numbers are shared across searches and extractions, so the model cites a fetched page the same way it cites a search result.

{
  "choices": [{"message": {"role": "assistant", "content": "<answer text> [1]"}, "finish_reason": "stop"}],
  "web_results": {
    "searches": [
      {
        "query": "<search query>",
        "results": [
          {
            "citation": 1,
            "title": "<page title>",
            "url": "https://example.com/page",
            "snippet": "<extracted highlight>",
            "published_at": "<publication date>"
          }
        ]
      }
    ],
    "extracts": []
  }
}

web_results is absent when no search or fetch ran. In a stream, it arrives on the final chunk. Before it, the router sends named web_search and web_extract events that report each step with fields such as status, round, query, result_count, and duration_ms.

Unsupported Shapes

The router returns 400 for other web-search shapes instead of grounding them silently:

• The web_search_options field.
• Tool types web_search_preview and any web_search_* type on /v1/chat/completions.
• A tool named WebSearch with no input_schema.
• Function tools named litellm_web_search, you_web_search, or you_web_extract.

Anthropic Web Search on Messages

On /v1/messages, declare Anthropic’s versioned web_search_* server tool, such as web_search_20250305. The router answers it with You.com search and returns server_tool_use and web_search_tool_result blocks for every search it ran.

curl https://api.you.com/v1/messages \
  -H "Authorization: Bearer $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What changed in the latest Python release?"}],
    "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]
  }'

Only one web search tool is allowed per request. The web_search and web_extract tool types are not documented for /v1/messages.