The TypeScript SDK and docs are currently in beta.
Report issues on GitHub.
Example Usage
import { WebSearchServerToolConfig } from "@openrouter/sdk/models";
let value: WebSearchServerToolConfig = {};
Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
allowedDomains | string[] | :heavy_minus_sign: | Limit search results to these domains. Supported by Exa, Firecrawl, Parallel, and most native providers (Anthropic, OpenAI, xAI). Not supported with Perplexity. Cannot be used with excluded_domains. | |
engine | models.WebSearchEngineEnum | :heavy_minus_sign: | Which search engine to use. “auto” (default) uses native if the provider supports it, otherwise Exa. “native” forces the provider’s built-in search. “exa” forces the Exa search API. “firecrawl” uses Firecrawl (requires BYOK). “parallel” uses the Parallel search API. | auto |
excludedDomains | string[] | :heavy_minus_sign: | Exclude search results from these domains. Supported by Exa, Firecrawl, Parallel, Anthropic, and xAI. Not supported with OpenAI (silently ignored) or Perplexity. Cannot be used with allowed_domains. | |
maxResults | number | :heavy_minus_sign: | Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search. | 5 |
maxTotalResults | number | :heavy_minus_sign: | Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops. Defaults to 50 when not specified. | 50 |
searchContextSize | models.SearchQualityLevel | :heavy_minus_sign: | How much context to retrieve per result. Applies to Exa and Parallel engines; ignored with native provider search and Firecrawl. For Exa, pins a fixed per-result character cap (low=5,000, medium=15,000, high=30,000); when omitted, Exa picks an adaptive size per query and document (typically ~2,000–4,000 characters per result). For Parallel, controls the total characters across all results; when omitted, Parallel uses its own default size. | medium |
userLocation | models.WebSearchUserLocationServerTool | :heavy_minus_sign: | Approximate user location for location-biased results. | {"city": "San Francisco","country": "US","region": "California","timezone": "America/Los_Angeles","type": "approximate"} |