fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225)

feat(access-policies): limit which websites API requests can reach (#2213)

feat(brand): support log-free brand and styleguide requests (#2231)

fix(brand): keep metadata-only usage logs for ZDR brand requests (#2234)

feat(monitors): add search target to watch the web for new developments (#2215)

Stainless-Generated-From: e9cdf82d83cd475d9dc2cd5ede9284207a0559f9

Author: stlc-bot

src/context/dev/resources/monitors.py

@@ -96,10 +96,11 @@ def create(
         Args:
           name: Display name for the monitor.
 
-          target: What to watch: a page, a sitemap, or data extracted from a site.
+          target: What to watch: a page, a sitemap, data extracted from a site, or web search
+              results.
 
-          change_detection: How changes are judged. Defaults to `semantic` for extract targets and page
-              targets with `instructions`, otherwise `exact`.
+          change_detection: How changes are judged. Defaults to `semantic` for extract and search targets
+              and page targets with `instructions`, otherwise `exact`.
 
           mode: Always `web`. Optional.
 
@@ -204,8 +205,8 @@ def update(
         Args:
           monitor_id: ID of the monitor.
 
-          change_detection: How changes are judged. Defaults to `semantic` for extract targets and page
-              targets with `instructions`, otherwise `exact`.
+          change_detection: How changes are judged. Defaults to `semantic` for extract and search targets
+              and page targets with `instructions`, otherwise `exact`.
 
           name: Display name for the monitor.
 
@@ -219,7 +220,8 @@ def update(
 
           tags: Labels for filtering monitors, their changes, and their usage.
 
-          target: What to watch: a page, a sitemap, or data extracted from a site.
+          target: What to watch: a page, a sitemap, data extracted from a site, or web search
+              results.
 
           webhook: Set to null to remove the webhook. Changing `url` issues a new secret.
 
@@ -266,7 +268,7 @@ def list(
         status: Literal["active", "paused", "failed"] | Omit = omit,
         tag: str | Omit = omit,
         tags: Optional[SequenceNotStr[str]] | Omit = omit,
-        target_type: Literal["page", "sitemap", "extract"] | Omit = omit,
+        target_type: Literal["page", "sitemap", "extract", "search"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -286,8 +288,8 @@ def list(
 
           q: Free-text search term, matched against the fields named in `search_by`.
 
-          search_by: Fields to search with `q`. Defaults to all fields; page and extract targets can
-              have instructions.
+          search_by: Fields to search with `q`. Defaults to all fields; page, extract, and search
+              targets can have instructions, and `url` matches a search target’s query.
 
           search_type: `prefix` for as-you-type prefix matching (default), `exact` for full-token
               matching.
@@ -444,7 +446,7 @@ def list_account_changes(
         monitor_id: str | Omit = omit,
         since: Union[str, datetime] | Omit = omit,
         tag: str | Omit = omit,
-        target_type: Literal["page", "sitemap", "extract"] | Omit = omit,
+        target_type: Literal["page", "sitemap", "extract", "search"] | Omit = omit,
         until: Union[str, datetime] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -870,10 +872,11 @@ async def create(
         Args:
           name: Display name for the monitor.
 
-          target: What to watch: a page, a sitemap, or data extracted from a site.
+          target: What to watch: a page, a sitemap, data extracted from a site, or web search
+              results.
 
-          change_detection: How changes are judged. Defaults to `semantic` for extract targets and page
-              targets with `instructions`, otherwise `exact`.
+          change_detection: How changes are judged. Defaults to `semantic` for extract and search targets
+              and page targets with `instructions`, otherwise `exact`.
 
           mode: Always `web`. Optional.
 
@@ -978,8 +981,8 @@ async def update(
         Args:
           monitor_id: ID of the monitor.
 
-          change_detection: How changes are judged. Defaults to `semantic` for extract targets and page
-              targets with `instructions`, otherwise `exact`.
+          change_detection: How changes are judged. Defaults to `semantic` for extract and search targets
+              and page targets with `instructions`, otherwise `exact`.
 
           name: Display name for the monitor.
 
@@ -993,7 +996,8 @@ async def update(
 
           tags: Labels for filtering monitors, their changes, and their usage.
 
-          target: What to watch: a page, a sitemap, or data extracted from a site.
+          target: What to watch: a page, a sitemap, data extracted from a site, or web search
+              results.
 
           webhook: Set to null to remove the webhook. Changing `url` issues a new secret.
 
@@ -1040,7 +1044,7 @@ async def list(
         status: Literal["active", "paused", "failed"] | Omit = omit,
         tag: str | Omit = omit,
         tags: Optional[SequenceNotStr[str]] | Omit = omit,
-        target_type: Literal["page", "sitemap", "extract"] | Omit = omit,
+        target_type: Literal["page", "sitemap", "extract", "search"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -1060,8 +1064,8 @@ async def list(
 
           q: Free-text search term, matched against the fields named in `search_by`.
 
-          search_by: Fields to search with `q`. Defaults to all fields; page and extract targets can
-              have instructions.
+          search_by: Fields to search with `q`. Defaults to all fields; page, extract, and search
+              targets can have instructions, and `url` matches a search target’s query.
 
           search_type: `prefix` for as-you-type prefix matching (default), `exact` for full-token
               matching.
@@ -1218,7 +1222,7 @@ async def list_account_changes(
         monitor_id: str | Omit = omit,
         since: Union[str, datetime] | Omit = omit,
         tag: str | Omit = omit,
-        target_type: Literal["page", "sitemap", "extract"] | Omit = omit,
+        target_type: Literal["page", "sitemap", "extract", "search"] | Omit = omit,
         until: Union[str, datetime] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.

src/context/dev/types/monitor_create_params.py

@@ -19,6 +19,7 @@
     "TargetMonitorsPageTargetActionWebScrapeScrollAction",
     "TargetMonitorsSitemapTarget",
     "TargetMonitorsExtractTarget",
+    "TargetMonitorsSearchTarget",
     "ChangeDetection",
     "ChangeDetectionMonitorsExactChangeDetection",
     "ChangeDetectionMonitorsSemanticChangeDetection",
@@ -32,13 +33,16 @@ class MonitorCreateParams(TypedDict, total=False):
     """Display name for the monitor."""
 
     target: Required[Target]
-    """What to watch: a page, a sitemap, or data extracted from a site."""
+    """
+    What to watch: a page, a sitemap, data extracted from a site, or web search
+    results.
+    """
 
     change_detection: ChangeDetection
     """How changes are judged.
 
-    Defaults to `semantic` for extract targets and page targets with `instructions`,
-    otherwise `exact`.
+    Defaults to `semantic` for extract and search targets and page targets with
+    `instructions`, otherwise `exact`.
     """
 
     mode: Literal["web"]
@@ -205,17 +209,37 @@ class TargetMonitorsExtractTarget(TypedDict, total=False):
     """
 
 
-Target: TypeAlias = Union[TargetMonitorsPageTarget, TargetMonitorsSitemapTarget, TargetMonitorsExtractTarget]
+class TargetMonitorsSearchTarget(TypedDict, total=False):
+    """
+    Search the web on every run and report results not seen before, listed in the change’s `matched_urls` and `evidence`. Semantic detection reports only results describing a new development that matches `instructions`; exact detection reports every new result.
+    """
+
+    query: Required[str]
+    """Web search query to run on every check.
+
+    Supports operators such as `site:`, `-site:`, and quoted phrases.
+    """
+
+    type: Required[Literal["search"]]
+    """Use `search` to watch the whole web for new results about a topic."""
+
+    instructions: str
+    """Plain-language description of which new results matter. Defaults to the query."""
+
+
+Target: TypeAlias = Union[
+    TargetMonitorsPageTarget, TargetMonitorsSitemapTarget, TargetMonitorsExtractTarget, TargetMonitorsSearchTarget
+]
 
 
 class ChangeDetectionMonitorsExactChangeDetection(TypedDict, total=False):
     """Detect exact changes.
 
-    For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
+    For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals. For search targets, this means every new result.
     """
 
     type: Required[Literal["exact"]]
-    """Use `exact` to compare visible text or sitemap URLs."""
+    """Use `exact` to compare visible text, sitemap URLs, or search results."""
 
 
 class ChangeDetectionMonitorsSemanticChangeDetection(TypedDict, total=False):

src/context/dev/types/monitor_create_response.py

@@ -23,10 +23,13 @@
     "TargetMonitorsPageTargetActionWebScrapeScrollAction",
     "TargetMonitorsSitemapTarget",
     "TargetMonitorsExtractTarget",
+    "TargetMonitorsSearchTarget",
     "Baseline",
     "BaselineMonitorsPageBaseline",
     "BaselineMonitorsSitemapBaseline",
     "BaselineMonitorsExtractBaseline",
+    "BaselineMonitorsSearchBaseline",
+    "BaselineMonitorsSearchBaselineResult",
     "KeyMetadata",
     "LastError",
     "Schedule",
@@ -38,11 +41,11 @@
 class ChangeDetectionMonitorsExactChangeDetection(BaseModel):
     """Detect exact changes.
 
-    For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
+    For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals. For search targets, this means every new result.
     """
 
     type: Literal["exact"]
-    """Use `exact` to compare visible text or sitemap URLs."""
+    """Use `exact` to compare visible text, sitemap URLs, or search results."""
 
 
 class ChangeDetectionMonitorsSemanticChangeDetection(BaseModel):
@@ -210,8 +213,28 @@ class TargetMonitorsExtractTarget(BaseModel):
     """
 
 
+class TargetMonitorsSearchTarget(BaseModel):
+    """
+    Search the web on every run and report results not seen before, listed in the change’s `matched_urls` and `evidence`. Semantic detection reports only results describing a new development that matches `instructions`; exact detection reports every new result.
+    """
+
+    query: str
+    """Web search query to run on every check.
+
+    Supports operators such as `site:`, `-site:`, and quoted phrases.
+    """
+
+    type: Literal["search"]
+    """Use `search` to watch the whole web for new results about a topic."""
+
+    instructions: Optional[str] = None
+    """Plain-language description of which new results matter. Defaults to the query."""
+
+
 Target: TypeAlias = Annotated[
-    Union[TargetMonitorsPageTarget, TargetMonitorsSitemapTarget, TargetMonitorsExtractTarget],
+    Union[
+        TargetMonitorsPageTarget, TargetMonitorsSitemapTarget, TargetMonitorsExtractTarget, TargetMonitorsSearchTarget
+    ],
     PropertyInfo(discriminator="type"),
 ]
 
@@ -259,8 +282,34 @@ class BaselineMonitorsExtractBaseline(BaseModel):
     """The page URLs the monitor tracks and analyzes for changes."""
 
 
+class BaselineMonitorsSearchBaselineResult(BaseModel):
+    description: str
+    """Result snippet."""
+
+    published_at: Optional[datetime] = None
+    """When the result was published, when known."""
+
+    title: str
+
+    url: str
+
+
+class BaselineMonitorsSearchBaseline(BaseModel):
+    """Current baseline of a `search` monitor: the search results as last observed."""
+
+    captured_at: datetime
+    """When this baseline was last captured or replaced."""
+
+    results: List[BaselineMonitorsSearchBaselineResult]
+    """Search results as last observed."""
+
+
 Baseline: TypeAlias = Union[
-    BaselineMonitorsPageBaseline, BaselineMonitorsSitemapBaseline, BaselineMonitorsExtractBaseline, None
+    BaselineMonitorsPageBaseline,
+    BaselineMonitorsSitemapBaseline,
+    BaselineMonitorsExtractBaseline,
+    BaselineMonitorsSearchBaseline,
+    None,
 ]
 
 
@@ -355,8 +404,8 @@ class MonitorCreateResponse(BaseModel):
     change_detection: ChangeDetection
     """How changes are judged.
 
-    Defaults to `semantic` for extract targets and page targets with `instructions`,
-    otherwise `exact`.
+    Defaults to `semantic` for extract and search targets and page targets with
+    `instructions`, otherwise `exact`.
     """
 
     created_at: datetime
@@ -386,7 +435,10 @@ class MonitorCreateResponse(BaseModel):
     """
 
     target: Target
-    """What to watch: a page, a sitemap, or data extracted from a site."""
+    """
+    What to watch: a page, a sitemap, data extracted from a site, or web search
+    results.
+    """
 
     updated_at: datetime
 

src/context/dev/types/monitor_list_account_changes_params.py

@@ -30,7 +30,7 @@ class MonitorListAccountChangesParams(TypedDict, total=False):
     tag: str
     """Filter to items that have this tag."""
 
-    target_type: Literal["page", "sitemap", "extract"]
+    target_type: Literal["page", "sitemap", "extract", "search"]
     """Filter by target type."""
 
     until: Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]

src/context/dev/types/monitor_list_account_changes_response.py

@@ -42,11 +42,12 @@ class Data(BaseModel):
     tags: List[str]
     """Labels for filtering monitors, their changes, and their usage."""
 
-    target_type: Literal["page", "sitemap", "extract"]
+    target_type: Literal["page", "sitemap", "extract", "search"]
 
     title: str
 
     url: str
+    """The monitored URL. For search targets, the first newly reported result."""
 
     added_url_count: Optional[int] = None
 

src/context/dev/types/monitor_list_account_runs_response.py

@@ -44,7 +44,7 @@ class Data(BaseModel):
     paused, or superseded by a concurrent run).
     """
 
-    target_type: Literal["page", "sitemap", "extract"]
+    target_type: Literal["page", "sitemap", "extract", "search"]
 
     change_id: Optional[str] = None
 

src/context/dev/types/monitor_list_changes_response.py

@@ -42,11 +42,12 @@ class Data(BaseModel):
     tags: List[str]
     """Labels for filtering monitors, their changes, and their usage."""
 
-    target_type: Literal["page", "sitemap", "extract"]
+    target_type: Literal["page", "sitemap", "extract", "search"]
 
     title: str
 
     url: str
+    """The monitored URL. For search targets, the first newly reported result."""
 
     added_url_count: Optional[int] = None
 

src/context/dev/types/monitor_list_params.py

@@ -26,7 +26,8 @@ class MonitorListParams(TypedDict, total=False):
     search_by: Optional[List[Literal["name", "url", "instructions", "tags"]]]
     """Fields to search with `q`.
 
-    Defaults to all fields; page and extract targets can have instructions.
+    Defaults to all fields; page, extract, and search targets can have instructions,
+    and `url` matches a search target’s query.
     """
 
     search_type: Literal["exact", "prefix"]
@@ -46,5 +47,5 @@ class MonitorListParams(TypedDict, total=False):
     Comma-separated list of tags to filter by (matches monitors having any of them).
     """
 
-    target_type: Literal["page", "sitemap", "extract"]
+    target_type: Literal["page", "sitemap", "extract", "search"]
     """Filter by target type."""