feat: Document name uniqueness and query match semantics

stainless-app[bot] · stainless-app[bot] · commit e27f37d43b1d · 2026-07-10T14:19:22.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 127
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-bc33d13e669972493e9ab0da82a71999822dc049eb14b113f446753c917ffcdb.yml
-openapi_spec_hash: 133a2e0d0cdc4023f98b3c2e589cf5d8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-6c7cbaefd8a84ec26a1677681f37041323290080dac3fd1a409bb7cd01dd2ae3.yml
+openapi_spec_hash: 75085a25c8a5cdb5417f0dbfad0ed6b6
 config_hash: 77ee715aa17061166f9a02b264a21b8d
diff --git a/src/kernel/resources/api_keys.py b/src/kernel/resources/api_keys.py
@@ -71,7 +71,7 @@ def create(
         Create a new API key within the authenticated organization.
 
         Args:
-          name: API key name (1-255 characters)
+          name: Label for the API key (1-255 characters). API keys are not addressable by name.
 
           days_to_expire: Number of days until expiry, up to 3650. Use null for never.
 
@@ -382,7 +382,7 @@ async def create(
         Create a new API key within the authenticated organization.
 
         Args:
-          name: API key name (1-255 characters)
+          name: Label for the API key (1-255 characters). API keys are not addressable by name.
 
           days_to_expire: Number of days until expiry, up to 3650. Use null for never.
 
diff --git a/src/kernel/resources/auth/connections.py b/src/kernel/resources/auth/connections.py
@@ -140,7 +140,9 @@ def create(
           login_url: Optional login page URL to skip discovery
 
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Whether to record browser sessions for this connection by default. Useful for
               debugging. Can be overridden per-login. Defaults to false.
@@ -268,7 +270,9 @@ def update(
           login_url: Login page URL. Set to empty string to clear.
 
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Whether to record browser sessions for this connection by default
 
@@ -465,7 +469,9 @@ def login(
 
         Args:
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Override the connection's default for recording this login's browser session.
               When omitted, the connection's record_session default is used.
@@ -717,7 +723,9 @@ async def create(
           login_url: Optional login page URL to skip discovery
 
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Whether to record browser sessions for this connection by default. Useful for
               debugging. Can be overridden per-login. Defaults to false.
@@ -845,7 +853,9 @@ async def update(
           login_url: Login page URL. Set to empty string to clear.
 
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Whether to record browser sessions for this connection by default
 
@@ -1042,7 +1052,9 @@ async def login(
 
         Args:
           proxy: Proxy selection. Provide either id or name. The proxy must be in the same
-              project as the resource referencing it.
+              project as the resource referencing it. When selecting by name, the name must
+              match exactly one active proxy in the project. Ambiguous names return a 400; use
+              id for stable references.
 
           record_session: Override the connection's default for recording this login's browser session.
               When omitted, the connection's record_session default is used.
diff --git a/src/kernel/resources/browser_pools.py b/src/kernel/resources/browser_pools.py
@@ -378,7 +378,8 @@ def list(
 
           offset: Offset the number of browser pools to return.
 
-          query: Search browser pools by name or ID.
+          query: Case-insensitive substring match against browser pool name. IDs match by exact
+              value.
 
           extra_headers: Send extra headers
 
@@ -945,7 +946,8 @@ def list(
 
           offset: Offset the number of browser pools to return.
 
-          query: Search browser pools by name or ID.
+          query: Case-insensitive substring match against browser pool name. IDs match by exact
+              value.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/resources/credential_providers.py b/src/kernel/resources/credential_providers.py
@@ -216,7 +216,8 @@ def list(
 
           offset: Offset the number of credential providers to return.
 
-          query: Search credential providers by name or ID.
+          query: Case-insensitive substring match against credential provider name. IDs match by
+              exact value.
 
           extra_headers: Send extra headers
 
@@ -534,7 +535,8 @@ def list(
 
           offset: Offset the number of credential providers to return.
 
-          query: Search credential providers by name or ID.
+          query: Case-insensitive substring match against credential provider name. IDs match by
+              exact value.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/resources/credentials.py b/src/kernel/resources/credentials.py
@@ -229,7 +229,8 @@ def list(
 
           offset: Number of results to skip
 
-          query: Search credentials by name, domain, or ID.
+          query: Case-insensitive substring match against credential name or domain. IDs match by
+              exact value.
 
           extra_headers: Send extra headers
 
@@ -534,7 +535,8 @@ def list(
 
           offset: Number of results to skip
 
-          query: Search credentials by name, domain, or ID.
+          query: Case-insensitive substring match against credential name or domain. IDs match by
+              exact value.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/resources/extensions.py b/src/kernel/resources/extensions.py
@@ -79,7 +79,8 @@ def list(
 
           offset: Offset the number of extensions to return.
 
-          query: Search extensions by name or ID.
+          query: Case-insensitive substring match against extension name. IDs match by exact
+              value.
 
           extra_headers: Send extra headers
 
@@ -355,7 +356,8 @@ def list(
 
           offset: Offset the number of extensions to return.
 
-          query: Search extensions by name or ID.
+          query: Case-insensitive substring match against extension name. IDs match by exact
+              value.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/resources/profiles.py b/src/kernel/resources/profiles.py
@@ -189,7 +189,7 @@ def list(
 
           offset: Offset the number of profiles to return.
 
-          query: Search profiles by name or ID.
+          query: Case-insensitive substring match against profile name or ID.
 
           extra_headers: Send extra headers
 
@@ -447,7 +447,7 @@ def list(
 
           offset: Offset the number of profiles to return.
 
-          query: Search profiles by name or ID.
+          query: Case-insensitive substring match against profile name or ID.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/resources/proxies.py b/src/kernel/resources/proxies.py
@@ -202,7 +202,8 @@ def list(
 
           offset: Offset the number of proxies to return.
 
-          query: Search proxies by name, host, IP address, or ID.
+          query: Case-insensitive substring match against proxy name, host, or IP address. IDs
+              match by exact value.
 
           extra_headers: Send extra headers
 
@@ -496,7 +497,8 @@ def list(
 
           offset: Offset the number of proxies to return.
 
-          query: Search proxies by name, host, IP address, or ID.
+          query: Case-insensitive substring match against proxy name, host, or IP address. IDs
+              match by exact value.
 
           extra_headers: Send extra headers
 
diff --git a/src/kernel/types/api_key.py b/src/kernel/types/api_key.py
@@ -41,7 +41,11 @@ class APIKey(BaseModel):
     """Masked version of the API key"""
 
     name: str
-    """API key name"""
+    """Label for the API key.
+
+    API keys are not addressable by name; use the ID or key identifier for stable
+    references.
+    """
 
     project_id: Optional[str] = None
     """Project identifier for project-scoped API keys. Null means org-wide."""
diff --git a/src/kernel/types/api_key_create_params.py b/src/kernel/types/api_key_create_params.py
@@ -10,7 +10,7 @@
 
 class APIKeyCreateParams(TypedDict, total=False):
     name: Required[str]
-    """API key name (1-255 characters)"""
+    """Label for the API key (1-255 characters). API keys are not addressable by name."""
 
     days_to_expire: Optional[int]
     """Number of days until expiry, up to 3650. Use null for never."""
diff --git a/src/kernel/types/auth/connection_create_params.py b/src/kernel/types/auth/connection_create_params.py
@@ -84,7 +84,9 @@ class ConnectionCreateParams(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource
-    referencing it.
+    referencing it. When selecting by name, the name must match exactly one active
+    proxy in the project. Ambiguous names return a 400; use id for stable
+    references.
     """
 
     record_session: bool
@@ -126,6 +128,7 @@ class Proxy(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource referencing it.
+    When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references.
     """
 
     id: str
diff --git a/src/kernel/types/auth/connection_login_params.py b/src/kernel/types/auth/connection_login_params.py
@@ -12,7 +12,9 @@ class ConnectionLoginParams(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource
-    referencing it.
+    referencing it. When selecting by name, the name must match exactly one active
+    proxy in the project. Ambiguous names return a 400; use id for stable
+    references.
     """
 
     record_session: bool
@@ -26,6 +28,7 @@ class Proxy(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource referencing it.
+    When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references.
     """
 
     id: str
diff --git a/src/kernel/types/auth/connection_update_params.py b/src/kernel/types/auth/connection_update_params.py
@@ -51,7 +51,9 @@ class ConnectionUpdateParams(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource
-    referencing it.
+    referencing it. When selecting by name, the name must match exactly one active
+    proxy in the project. Ambiguous names return a 400; use id for stable
+    references.
     """
 
     record_session: bool
@@ -87,6 +89,7 @@ class Proxy(TypedDict, total=False):
     """Proxy selection.
 
     Provide either id or name. The proxy must be in the same project as the resource referencing it.
+    When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references.
     """
 
     id: str
diff --git a/src/kernel/types/browser_pool_list_params.py b/src/kernel/types/browser_pool_list_params.py
@@ -15,4 +15,7 @@ class BrowserPoolListParams(TypedDict, total=False):
     """Offset the number of browser pools to return."""
 
     query: str
-    """Search browser pools by name or ID."""
+    """Case-insensitive substring match against browser pool name.
+
+    IDs match by exact value.
+    """
diff --git a/src/kernel/types/credential_list_params.py b/src/kernel/types/credential_list_params.py
@@ -18,4 +18,7 @@ class CredentialListParams(TypedDict, total=False):
     """Number of results to skip"""
 
     query: str
-    """Search credentials by name, domain, or ID."""
+    """Case-insensitive substring match against credential name or domain.
+
+    IDs match by exact value.
+    """
diff --git a/src/kernel/types/credential_provider_list_params.py b/src/kernel/types/credential_provider_list_params.py
@@ -15,4 +15,7 @@ class CredentialProviderListParams(TypedDict, total=False):
     """Offset the number of credential providers to return."""
 
     query: str
-    """Search credential providers by name or ID."""
+    """Case-insensitive substring match against credential provider name.
+
+    IDs match by exact value.
+    """
diff --git a/src/kernel/types/extension_list_params.py b/src/kernel/types/extension_list_params.py
@@ -15,4 +15,7 @@ class ExtensionListParams(TypedDict, total=False):
     """Offset the number of extensions to return."""
 
     query: str
-    """Search extensions by name or ID."""
+    """Case-insensitive substring match against extension name.
+
+    IDs match by exact value.
+    """
diff --git a/src/kernel/types/profile_list_params.py b/src/kernel/types/profile_list_params.py
@@ -15,4 +15,4 @@ class ProfileListParams(TypedDict, total=False):
     """Offset the number of profiles to return."""
 
     query: str
-    """Search profiles by name or ID."""
+    """Case-insensitive substring match against profile name or ID."""
diff --git a/src/kernel/types/proxy_list_params.py b/src/kernel/types/proxy_list_params.py
@@ -15,4 +15,7 @@ class ProxyListParams(TypedDict, total=False):
     """Offset the number of proxies to return."""
 
     query: str
-    """Search proxies by name, host, IP address, or ID."""
+    """Case-insensitive substring match against proxy name, host, or IP address.
+
+    IDs match by exact value.
+    """
