group_query
Find rooms, floors, zones, homes and device groups, with their members and supported controls.
Returns canonical IDs, names, etags, spatial roles, parent paths, children, member devices, controllers and providers. Call it without arguments first to load full context and follow every paginationContext.nextToken; filter with query only when the account is large.
Controllers are the endpoints that can act on the group, with the message IDs that accept it: to clean a room, call control on the controller endpoint with one of those message IDs and payload {"groupIds": []}.
Messages are message IDs the group itself accepts: send one with control, using the group ID as id. Port OS uses a native group only when it respects effective membership; otherwise it dispatches equivalent actions to individual members or returns unsupported. Disabled provider routes are never control candidates. Room cleaning is not a group message; use the controller as above. If two groups match a spoken room name, ask the user which one, naming each group's parentPath.
Pass id to read one group; a merged group ID resolves to the surviving group and reports redirectedFrom.
To show a room map or let someone pick rooms, call endpoint_show on the vacuum (controller) with primary house-map; never draw a map yourself from spatial geometry.
Expand accepts capability names as in endpoint_query (for example ["speaker","media-player"]); forceDeviceAttributeQuery refreshes those observations. Read route attribute status before trusting a value: omitted or failed fresh values are unavailable.
Each route's membershipComplete is provider-declared: false means incomplete or unreported, and absent means unknown. members lists resolved endpoints, so an empty list does not prove a provider group has no members.
Disabled groups are hidden unless enablement is DISABLED or *; they cannot be targeted, and group_manage SET_ENABLEMENT enables them again. Copy group IDs and etags verbatim into control and group_manage.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Return one group by its full group ID. Cannot be combined with query, maxResults or nextToken. | |
| query | No | Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"role": {"eq": "ROOM"}, "name": {"like": "kitchen"}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: id (text) full group ID; name (text) group name; role (text) spatial role a provider declares: HOME, FLOOR, ROOM or ZONE; parentGroupId (text) ID of the containing group; ownerId (text, eq only at the top level) principal whose groups to list; defaults to the caller; children (list) IDs of contained groups; members (list) member endpoint IDs; controllers (list) IDs of endpoints that can act on the group, such as a robot that cleans the room; messages (list) full message IDs the group itself accepts; providers (list) names of the plugins that report the group. | |
| expand | No | Select declared capabilities whose route observations to return, for example ["speaker", "media-player"]. Requires id. This adds state readings to the selected group; it does not expand group membership or send commands. Expanding spatial returns raw room geometry for reading only. To show a map or let someone pick rooms, call endpoint_show on the vacuum with primary house-map; never draw one yourself. | |
| nextToken | No | Opaque cursor returned by a previous group_query call with the same query and maxResults. | |
| enablement | No | Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination; id reads ignore it. | ENABLED |
| maxResults | No | Maximum number of groups (default 25, maximum 100). | |
| forceDeviceAttributeQuery | No | Requires id and nonempty expand; refresh provider state before returning route observations. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||