feat(api): add web search filters

stainless-app[bot] · stainless-app[bot] · commit dd30c8788ce0 · 2025-08-26T20:49:16.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 119
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-ddbdf9343316047e8a773c54fb24e4a8d225955e202a1888fde6f9c8898ebf98.yml
-openapi_spec_hash: 9802f6dd381558466c897f6e387e06ca
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-8517ffa1004e31ca2523d617629e64be6fe4f13403ddfd9db5b3be002656cbde.yml
+openapi_spec_hash: b64dd8c8b23082a7aa2a3e5c5fffd8bd
 config_hash: fe0ea26680ac2075a6cd66416aefe7db
diff --git a/src/resources/conversations/conversations.ts b/src/resources/conversations/conversations.ts
@@ -22,7 +22,7 @@ export class Conversations extends APIResource {
   items: ItemsAPI.Items = new ItemsAPI.Items(this._client);
 
   /**
-   * Create a conversation with the given ID.
+   * Create a conversation.
    */
   create(body: ConversationCreateParams, options?: RequestOptions): APIPromise<Conversation> {
     return this._client.post('/conversations', { body, ...options });
diff --git a/src/resources/conversations/items.ts b/src/resources/conversations/items.ts
@@ -438,6 +438,8 @@ export interface ItemListParams extends ConversationCursorPageParams {
    * Specify additional output data to include in the model response. Currently
    * supported values are:
    *
+   * - `web_search_call.action.sources`: Include the sources of the web search tool
+   *   call.
    * - `code_interpreter_call.outputs`: Includes the outputs of python code execution
    *   in code interpreter tool call items.
    * - `computer_call_output.output.image_url`: Include image urls from the computer
diff --git a/src/resources/responses/responses.ts b/src/resources/responses/responses.ts
@@ -1949,6 +1949,28 @@ export namespace ResponseFunctionWebSearch {
      * The action type.
      */
     type: 'search';
+
+    /**
+     * The sources used in the search.
+     */
+    sources?: Array<Search.Source>;
+  }
+
+  export namespace Search {
+    /**
+     * A source used in the search.
+     */
+    export interface Source {
+      /**
+       * The type of source. Always `url`.
+       */
+      type: 'url';
+
+      /**
+       * The URL of the source.
+       */
+      url: string;
+    }
   }
 
   /**
@@ -2124,6 +2146,12 @@ export interface ResponseInProgressEvent {
  * Specify additional output data to include in the model response. Currently
  * supported values are:
  *
+ * - `web_search_call.action.sources`: Include the sources of the web search tool
+ *   call.
+ * - `code_interpreter_call.outputs`: Includes the outputs of python code execution
+ *   in code interpreter tool call items.
+ * - `computer_call_output.output.image_url`: Include image urls from the computer
+ *   call output.
  * - `file_search_call.results`: Include the search results of the file search tool
  *   call.
  * - `message.input_image.image_url`: Include image urls from the input message.
@@ -4625,15 +4653,90 @@ export interface ResponseWebSearchCallSearchingEvent {
 export type Tool =
   | FunctionTool
   | FileSearchTool
-  | WebSearchTool
   | ComputerTool
+  | Tool.WebSearchTool
   | Tool.Mcp
   | Tool.CodeInterpreter
   | Tool.ImageGeneration
   | Tool.LocalShell
-  | CustomTool;
+  | CustomTool
+  | WebSearchTool;
 
 export namespace Tool {
+  /**
+   * Search the Internet for sources related to the prompt. Learn more about the
+   * [web search tool](https://platform.openai.com/docs/guides/tools-web-search).
+   */
+  export interface WebSearchTool {
+    /**
+     * The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.
+     */
+    type: 'web_search' | 'web_search_2025_08_26';
+
+    /**
+     * Filters for the search.
+     */
+    filters?: WebSearchTool.Filters | null;
+
+    /**
+     * High level guidance for the amount of context window space to use for the
+     * search. One of `low`, `medium`, or `high`. `medium` is the default.
+     */
+    search_context_size?: 'low' | 'medium' | 'high';
+
+    /**
+     * The approximate location of the user.
+     */
+    user_location?: WebSearchTool.UserLocation | null;
+  }
+
+  export namespace WebSearchTool {
+    /**
+     * Filters for the search.
+     */
+    export interface Filters {
+      /**
+       * Allowed domains for the search. If not provided, all domains are allowed.
+       * Subdomains of the provided domains are allowed as well.
+       *
+       * Example: `["pubmed.ncbi.nlm.nih.gov"]`
+       */
+      allowed_domains?: Array<string> | null;
+    }
+
+    /**
+     * The approximate location of the user.
+     */
+    export interface UserLocation {
+      /**
+       * Free text input for the city of the user, e.g. `San Francisco`.
+       */
+      city?: string | null;
+
+      /**
+       * The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+       * the user, e.g. `US`.
+       */
+      country?: string | null;
+
+      /**
+       * Free text input for the region of the user, e.g. `California`.
+       */
+      region?: string | null;
+
+      /**
+       * The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+       * user, e.g. `America/Los_Angeles`.
+       */
+      timezone?: string | null;
+
+      /**
+       * The type of location approximation. Always `approximate`.
+       */
+      type?: 'approximate';
+    }
+  }
+
   /**
    * Give the model access to additional tools via remote Model Context Protocol
    * (MCP) servers.
@@ -5122,6 +5225,12 @@ export interface ResponseCreateParamsBase {
    * Specify additional output data to include in the model response. Currently
    * supported values are:
    *
+   * - `web_search_call.action.sources`: Include the sources of the web search tool
+   *   call.
+   * - `code_interpreter_call.outputs`: Includes the outputs of python code execution
+   *   in code interpreter tool call items.
+   * - `computer_call_output.output.image_url`: Include image urls from the computer
+   *   call output.
    * - `file_search_call.results`: Include the search results of the file search tool
    *   call.
    * - `message.input_image.image_url`: Include image urls from the input message.

Original file line number	Diff line number	Diff line change
`@@ -438,6 +438,8 @@ export interface ItemListParams extends ConversationCursorPageParams {`
`438`	`438`	`* Specify additional output data to include in the model response. Currently`
`439`	`439`	`* supported values are:`
`440`	`440`	`*`
	`441`	+ * - `web_search_call.action.sources`: Include the sources of the web search tool
	`442`	`+ * call.`
`441`	`443`	* - `code_interpreter_call.outputs`: Includes the outputs of python code execution
`442`	`444`	`* in code interpreter tool call items.`
`443`	`445`	* - `computer_call_output.output.image_url`: Include image urls from the computer