feat(api): allow setting key-value tags on a browser session at create time

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-d0f7d8820ee342b6b8e32d5c08620d7a31135a6aabbe8266118b54269fbabb9d.yml
-openapi_spec_hash: 371eb419c25eb160fbc0135e45c133d1
-config_hash: 36159c262d293fbeacf513ab600a1729
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-8f84f4214a8024d8ea62ee639eeaf2fa26900fabe23c8b87accb41d529a0bf4f.yml
+openapi_spec_hash: db14f415438b3d338d9376bddc83a5cf
+config_hash: 590bf8cb85948cf1e63b7b5ef60686c8

api.md

@@ -83,6 +83,7 @@ from kernel.types import (
     BrowserPoolRef,
     BrowserUsage,
     Profile,
+    Tags,
     BrowserCreateResponse,
     BrowserRetrieveResponse,
     BrowserUpdateResponse,

src/kernel/resources/browsers/browsers.py

@@ -85,6 +85,7 @@
 )
 from ...pagination import SyncOffsetPagination, AsyncOffsetPagination
 from ..._base_client import AsyncPaginator, make_request_options
+from ...types.tags_param import TagsParam
 from ...types.browser_curl_response import BrowserCurlResponse
 from ...types.browser_list_response import BrowserListResponse
 from ...lib.browser_routing.raw_http import (
@@ -174,6 +175,7 @@ def create(
         proxy_id: str | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        tags: TagsParam | Omit = omit,
         telemetry: Optional[browser_create_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
@@ -224,6 +226,9 @@ def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
 
+          tags: Optional user-defined key-value tags for the browser session, used to find and
+              group sessions later. Set at creation time only. Up to 50 pairs.
+
           telemetry: Telemetry configuration for the browser session. Set enabled to true to start
               capture using VM defaults, or provide browser category settings. If omitted,
               null, set to an empty object ({}), set to enabled: false without browser
@@ -272,6 +277,7 @@ def create(
                     "proxy_id": proxy_id,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "tags": tags,
                     "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
@@ -399,6 +405,7 @@ def list(
         offset: int | Omit = omit,
         query: str | Omit = omit,
         status: Literal["active", "deleted", "all"] | Omit = omit,
+        tags: Dict[str, str] | 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,
@@ -424,6 +431,10 @@ def list(
           status: Filter sessions by status. "active" returns only active sessions (default),
               "deleted" returns only soft-deleted sessions, "all" returns both.
 
+          tags: Filter sessions by tag key-value pairs using deepObject style, e.g.
+              ?tags[team]=backend&tags[env]=staging. Multiple pairs are ANDed: a session must
+              match every supplied pair exactly.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -447,6 +458,7 @@ def list(
                         "offset": offset,
                         "query": query,
                         "status": status,
+                        "tags": tags,
                     },
                     browser_list_params.BrowserListParams,
                 ),
@@ -728,6 +740,7 @@ async def create(
         proxy_id: str | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        tags: TagsParam | Omit = omit,
         telemetry: Optional[browser_create_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
@@ -778,6 +791,9 @@ async def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
 
+          tags: Optional user-defined key-value tags for the browser session, used to find and
+              group sessions later. Set at creation time only. Up to 50 pairs.
+
           telemetry: Telemetry configuration for the browser session. Set enabled to true to start
               capture using VM defaults, or provide browser category settings. If omitted,
               null, set to an empty object ({}), set to enabled: false without browser
@@ -826,6 +842,7 @@ async def create(
                     "proxy_id": proxy_id,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "tags": tags,
                     "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
@@ -953,6 +970,7 @@ def list(
         offset: int | Omit = omit,
         query: str | Omit = omit,
         status: Literal["active", "deleted", "all"] | Omit = omit,
+        tags: Dict[str, str] | 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,
@@ -978,6 +996,10 @@ def list(
           status: Filter sessions by status. "active" returns only active sessions (default),
               "deleted" returns only soft-deleted sessions, "all" returns both.
 
+          tags: Filter sessions by tag key-value pairs using deepObject style, e.g.
+              ?tags[team]=backend&tags[env]=staging. Multiple pairs are ANDed: a session must
+              match every supplied pair exactly.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1001,6 +1023,7 @@ def list(
                         "offset": offset,
                         "query": query,
                         "status": status,
+                        "tags": tags,
                     },
                     browser_list_params.BrowserListParams,
                 ),

src/kernel/types/__init__.py

@@ -4,6 +4,7 @@
 
 from . import browsers
 from .. import _compat
+from .tags import Tags as Tags
 from .shared import (
     LogEvent as LogEvent,
     AppAction as AppAction,
@@ -19,6 +20,7 @@
 from .profile import Profile as Profile
 from .project import Project as Project
 from .credential import Credential as Credential
+from .tags_param import TagsParam as TagsParam
 from .browser_pool import BrowserPool as BrowserPool
 from .browser_usage import BrowserUsage as BrowserUsage
 from .app_list_params import AppListParams as AppListParams

src/kernel/types/browser_create_params.py

@@ -5,6 +5,7 @@
 from typing import Dict, Iterable, Optional
 from typing_extensions import TypedDict
 
+from .tags_param import TagsParam
 from .shared_params.browser_profile import BrowserProfile
 from .shared_params.browser_viewport import BrowserViewport
 from .shared_params.browser_extension import BrowserExtension
@@ -82,6 +83,12 @@ class BrowserCreateParams(TypedDict, total=False):
     mechanisms.
     """
 
+    tags: TagsParam
+    """
+    Optional user-defined key-value tags for the browser session, used to find and
+    group sessions later. Set at creation time only. Up to 50 pairs.
+    """
+
     telemetry: Optional[Telemetry]
     """Telemetry configuration for the browser session.
 

src/kernel/types/browser_create_response.py

@@ -3,6 +3,7 @@
 from typing import Dict, Optional
 from datetime import datetime
 
+from .tags import Tags
 from .profile import Profile
 from .._models import BaseModel
 from .browser_usage import BrowserUsage
@@ -84,6 +85,12 @@ class BrowserCreateResponse(BaseModel):
     browser actually loaded.
     """
 
+    tags: Optional[Tags] = None
+    """User-defined key-value tags that were set on this browser session, if any.
+
+    Echoed back when present.
+    """
+
     telemetry: Optional[BrowserTelemetryConfig] = None
     """Active telemetry configuration for the session, if any."""
 

src/kernel/types/browser_list_params.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Dict
 from typing_extensions import Literal, TypedDict
 
 __all__ = ["BrowserListParams"]
@@ -30,3 +31,10 @@ class BrowserListParams(TypedDict, total=False):
     "active" returns only active sessions (default), "deleted" returns only
     soft-deleted sessions, "all" returns both.
     """
+
+    tags: Dict[str, str]
+    """Filter sessions by tag key-value pairs using deepObject style, e.g.
+
+    ?tags[team]=backend&tags[env]=staging. Multiple pairs are ANDed: a session must
+    match every supplied pair exactly.
+    """

src/kernel/types/browser_list_response.py

@@ -3,6 +3,7 @@
 from typing import Dict, Optional
 from datetime import datetime
 
+from .tags import Tags
 from .profile import Profile
 from .._models import BaseModel
 from .browser_usage import BrowserUsage
@@ -84,6 +85,12 @@ class BrowserListResponse(BaseModel):
     browser actually loaded.
     """
 
+    tags: Optional[Tags] = None
+    """User-defined key-value tags that were set on this browser session, if any.
+
+    Echoed back when present.
+    """
+
     telemetry: Optional[BrowserTelemetryConfig] = None
     """Active telemetry configuration for the session, if any."""
 

src/kernel/types/browser_pool_acquire_response.py

@@ -3,6 +3,7 @@
 from typing import Dict, Optional
 from datetime import datetime
 
+from .tags import Tags
 from .profile import Profile
 from .._models import BaseModel
 from .browser_usage import BrowserUsage
@@ -84,6 +85,12 @@ class BrowserPoolAcquireResponse(BaseModel):
     browser actually loaded.
     """
 
+    tags: Optional[Tags] = None
+    """User-defined key-value tags that were set on this browser session, if any.
+
+    Echoed back when present.
+    """
+
     telemetry: Optional[BrowserTelemetryConfig] = None
     """Active telemetry configuration for the session, if any."""
 

src/kernel/types/browser_retrieve_response.py

@@ -3,6 +3,7 @@
 from typing import Dict, Optional
 from datetime import datetime
 
+from .tags import Tags
 from .profile import Profile
 from .._models import BaseModel
 from .browser_usage import BrowserUsage
@@ -84,6 +85,12 @@ class BrowserRetrieveResponse(BaseModel):
     browser actually loaded.
     """
 
+    tags: Optional[Tags] = None
+    """User-defined key-value tags that were set on this browser session, if any.
+
+    Echoed back when present.
+    """
+
     telemetry: Optional[BrowserTelemetryConfig] = None
     """Active telemetry configuration for the session, if any."""