feat(api): add web search filters

Author: stainless-app[bot]

.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

src/openai/resources/conversations/conversations.py

@@ -67,7 +67,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> Conversation:
         """
-        Create a conversation with the given ID.
+        Create a conversation.
 
         Args:
           items: Initial items to include in the conversation context. You may add up to 20 items
@@ -244,7 +244,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> Conversation:
         """
-        Create a conversation with the given ID.
+        Create a conversation.
 
         Args:
           items: Initial items to include in the conversation context. You may add up to 20 items

src/openai/resources/conversations/items.py

@@ -163,6 +163,8 @@ def list(
           include: 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
@@ -391,6 +393,8 @@ def list(
           include: 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

src/openai/resources/responses/responses.py

@@ -136,6 +136,8 @@ def create(
           include: 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
@@ -377,6 +379,8 @@ def create(
           include: 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
@@ -611,6 +615,8 @@ def create(
           include: 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
@@ -1524,6 +1530,8 @@ async def create(
           include: 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
@@ -1765,6 +1773,8 @@ async def create(
           include: 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
@@ -1999,6 +2009,8 @@ async def create(
           include: 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

src/openai/types/conversations/item_list_params.py

@@ -19,6 +19,8 @@ class ItemListParams(TypedDict, total=False):
 
     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

src/openai/types/responses/response_create_params.py

@@ -51,6 +51,8 @@ class ResponseCreateParamsBase(TypedDict, total=False):
 
     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

src/openai/types/responses/response_function_web_search.py

@@ -1,12 +1,20 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Union
+from typing import List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 
-__all__ = ["ResponseFunctionWebSearch", "Action", "ActionSearch", "ActionOpenPage", "ActionFind"]
+__all__ = ["ResponseFunctionWebSearch", "Action", "ActionSearch", "ActionSearchSource", "ActionOpenPage", "ActionFind"]
+
+
+class ActionSearchSource(BaseModel):
+    type: Literal["url"]
+    """The type of source. Always `url`."""
+
+    url: str
+    """The URL of the source."""
 
 
 class ActionSearch(BaseModel):
@@ -16,6 +24,9 @@ class ActionSearch(BaseModel):
     type: Literal["search"]
     """The action type."""
 
+    sources: Optional[List[ActionSearchSource]] = None
+    """The sources used in the search."""
+
 
 class ActionOpenPage(BaseModel):
     type: Literal["open_page"]

src/openai/types/responses/response_function_web_search_param.py

@@ -2,10 +2,25 @@
 
 from __future__ import annotations
 
-from typing import Union
+from typing import Union, Iterable
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-__all__ = ["ResponseFunctionWebSearchParam", "Action", "ActionSearch", "ActionOpenPage", "ActionFind"]
+__all__ = [
+    "ResponseFunctionWebSearchParam",
+    "Action",
+    "ActionSearch",
+    "ActionSearchSource",
+    "ActionOpenPage",
+    "ActionFind",
+]
+
+
+class ActionSearchSource(TypedDict, total=False):
+    type: Required[Literal["url"]]
+    """The type of source. Always `url`."""
+
+    url: Required[str]
+    """The URL of the source."""
 
 
 class ActionSearch(TypedDict, total=False):
@@ -15,6 +30,9 @@ class ActionSearch(TypedDict, total=False):
     type: Required[Literal["search"]]
     """The action type."""
 
+    sources: Iterable[ActionSearchSource]
+    """The sources used in the search."""
+
 
 class ActionOpenPage(TypedDict, total=False):
     type: Required[Literal["open_page"]]

src/openai/types/responses/tool.py

@@ -3,16 +3,19 @@
 from typing import Dict, List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
+from . import web_search_tool
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from .custom_tool import CustomTool
 from .computer_tool import ComputerTool
 from .function_tool import FunctionTool
-from .web_search_tool import WebSearchTool
 from .file_search_tool import FileSearchTool
 
 __all__ = [
     "Tool",
+    "WebSearchTool",
+    "WebSearchToolFilters",
+    "WebSearchToolUserLocation",
     "Mcp",
     "McpAllowedTools",
     "McpAllowedToolsMcpToolFilter",
@@ -29,6 +32,61 @@
 ]
 
 
+class WebSearchToolFilters(BaseModel):
+    allowed_domains: Optional[List[str]] = None
+    """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"]`
+    """
+
+
+class WebSearchToolUserLocation(BaseModel):
+    city: Optional[str] = None
+    """Free text input for the city of the user, e.g. `San Francisco`."""
+
+    country: Optional[str] = None
+    """
+    The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+    the user, e.g. `US`.
+    """
+
+    region: Optional[str] = None
+    """Free text input for the region of the user, e.g. `California`."""
+
+    timezone: Optional[str] = None
+    """
+    The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+    user, e.g. `America/Los_Angeles`.
+    """
+
+    type: Optional[Literal["approximate"]] = None
+    """The type of location approximation. Always `approximate`."""
+
+
+class WebSearchTool(BaseModel):
+    type: Literal["web_search", "web_search_2025_08_26"]
+    """The type of the web search tool.
+
+    One of `web_search` or `web_search_2025_08_26`.
+    """
+
+    filters: Optional[WebSearchToolFilters] = None
+    """Filters for the search."""
+
+    search_context_size: Optional[Literal["low", "medium", "high"]] = None
+    """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.
+    """
+
+    user_location: Optional[WebSearchToolUserLocation] = None
+    """The approximate location of the user."""
+
+
 class McpAllowedToolsMcpToolFilter(BaseModel):
     read_only: Optional[bool] = None
     """Indicates whether or not a tool modifies data or is read-only.
@@ -245,13 +303,14 @@ class LocalShell(BaseModel):
     Union[
         FunctionTool,
         FileSearchTool,
-        WebSearchTool,
         ComputerTool,
+        WebSearchTool,
         Mcp,
         CodeInterpreter,
         ImageGeneration,
         LocalShell,
         CustomTool,
+        web_search_tool.WebSearchTool,
     ],
     PropertyInfo(discriminator="type"),
 ]

src/openai/types/responses/tool_param.py

@@ -14,6 +14,9 @@
 
 __all__ = [
     "ToolParam",
+    "WebSearchTool",
+    "WebSearchToolFilters",
+    "WebSearchToolUserLocation",
     "Mcp",
     "McpAllowedTools",
     "McpAllowedToolsMcpToolFilter",
@@ -30,6 +33,61 @@
 ]
 
 
+class WebSearchToolFilters(TypedDict, total=False):
+    allowed_domains: Optional[List[str]]
+    """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"]`
+    """
+
+
+class WebSearchToolUserLocation(TypedDict, total=False):
+    city: Optional[str]
+    """Free text input for the city of the user, e.g. `San Francisco`."""
+
+    country: Optional[str]
+    """
+    The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+    the user, e.g. `US`.
+    """
+
+    region: Optional[str]
+    """Free text input for the region of the user, e.g. `California`."""
+
+    timezone: Optional[str]
+    """
+    The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+    user, e.g. `America/Los_Angeles`.
+    """
+
+    type: Literal["approximate"]
+    """The type of location approximation. Always `approximate`."""
+
+
+class WebSearchTool(TypedDict, total=False):
+    type: Required[Literal["web_search", "web_search_2025_08_26"]]
+    """The type of the web search tool.
+
+    One of `web_search` or `web_search_2025_08_26`.
+    """
+
+    filters: Optional[WebSearchToolFilters]
+    """Filters for the search."""
+
+    search_context_size: Literal["low", "medium", "high"]
+    """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.
+    """
+
+    user_location: Optional[WebSearchToolUserLocation]
+    """The approximate location of the user."""
+
+
 class McpAllowedToolsMcpToolFilter(TypedDict, total=False):
     read_only: bool
     """Indicates whether or not a tool modifies data or is read-only.
@@ -243,13 +301,14 @@ class LocalShell(TypedDict, total=False):
 ToolParam: TypeAlias = Union[
     FunctionToolParam,
     FileSearchToolParam,
-    WebSearchToolParam,
     ComputerToolParam,
+    WebSearchTool,
     Mcp,
     CodeInterpreter,
     ImageGeneration,
     LocalShell,
     CustomToolParam,
+    WebSearchToolParam,
 ]