[api] Connected Condition - state_subscription_only flag

content/components/api.md

@@ -381,25 +381,47 @@ api:
     - logger.log: "API client disconnected!"
 ```
 
+## Conditions
+
 {{< anchor "api-connected_condition" >}}
 
-## `api.connected` Condition
+### `api.connected` Condition
 
 This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome
-native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
-if logs are shown remotely.
+native API. Please note `client` refers to any connection to the API, including Home Assistant, ESPHome's remote log viewer, and other API consumers.
+
+Check if any client is connected:
 
 ```yaml
 on_...:
   if:
     condition:
       api.connected:
     then:
-      - logger.log: API is connected!
+      - logger.log: Client is connected to API!
 ```
 
 The lambda equivalent for this is `id(api_id).is_connected()`.
 
+Check if a client with state subscription (Home Assistant, Node-RED library) is connected:
+
+```yaml
+on_...:
+  if:
+    condition:
+      api.connected:
+        state_subscription_only: True
+    then:
+      - logger.log: Client with state subscription is connected to API!
+```
+
+The lambda equivalent for this is `id(api_id).is_connected(true)`.
+
+#### Configuration variables
+
+- **state_subscription_only** (*Optional*, boolean): If enabled, the condition checks for clients with state subscription (Home Assistant, Node-RED library) only.
+  Defaults to `false`.
+
 {{< anchor "api-device-actions" >}}
 
 ## User-defined Actions