Skip to content
Port OS

group_query

← MCP reference
View in MCP reference →
TOOL 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": [<group ID>]}.

Messages are message IDs the group itself accepts: send one with control, using the group ID as id, and Port OS dispatches it to the provider's group. 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.

Required scope

group:read

Input

Fields

enablementstring

Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination; id reads ignore it.

Default: ENABLED

Allowed values: ENABLED, DISABLED, *.

expandarray<string>

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.

forceDeviceAttributeQueryboolean

Requires id and nonempty expand; refresh provider state before returning route observations.

idstring

Return one group by its full group ID. Cannot be combined with query, maxResults or nextToken.

maxResultsinteger

Maximum number of groups (default 25, maximum 100).

minimum: 1

nextTokenstring

Opaque cursor returned by a previous group_query call with the same query and maxResults.

queryobject

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: the fields your connected devices declare, listed in the tool description returned by tools/list.

Result

Fields

paginationContextobject
redirectedFromstring
resultsarray<object>Required

Errors

A failed call returns this error object as its result instead.

Fields

familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.