group_manage
group_manageOrganize rooms and device groups: create, rename, change members, enable, disable, merge or delete them.
To hide a discovered group (such as a robot's room) for good, disable it with SET_ENABLEMENT: rediscovery may recreate a deleted discovered group but never re-enables a disabled one. This tool never performs physical control; use control to act on devices.
MERGE_INTO and DELETE_GROUP are destructive: describe exactly which groups will be merged or deleted and get the user's explicit confirmation before calling, and never infer that consent from an earlier request. Read each group with group_query first and pass its current etag; a stale etag fails with PRECONDITION_FAILED, so re-read and confirm again rather than retrying blindly.
Operations in one call apply atomically: either every operation commits or none does. Set validateOnly=true to check a batch without writing. idempotencyKey (required unless validateOnly) is a fresh unique string per intended change; reuse the same key only to retry that same request after an unknown outcome, which then returns the original result.
The result is the Port OS group management envelope: status COMMITTED or FAILED, results correlated by requestId, and errors listing every failing operation with code, family and message.
Required scope
group:manageInput
Fields
- idempotencyKey
string Unique key for this intended change, at most 255 characters. Required unless validateOnly is true.
- operations
array<EndpointGroupsManageOperation>Required Ordered operations applied atomically.
One endpoint group management operation, discriminated by `operation`. Unknown operations are rejected with 400.
discriminator: operation
- EndpointGroupsCreateGroupOperation
EndpointGroupsCreateGroupOperation Creates a user group. Its new ID and etag are returned in the result; later operations in the same batch cannot reference it. A user group name is `{"type": "PLAIN", "value": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.
Selected when operation is CREATE_GROUP
- EndpointGroupsDeleteGroupOperation
EndpointGroupsDeleteGroupOperation Deletes a group.
Selected when operation is DELETE_GROUP
- EndpointGroupsSetNameOperation
EndpointGroupsSetNameOperation Renames a group. The name is a user override that survives rediscovery. A user group name is `{"type": "PLAIN", "value": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST.
Selected when operation is SET_NAME
- EndpointGroupsAddMembersOperation
EndpointGroupsAddMembersOperation Adds endpoint members to a group. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.
Selected when operation is ADD_MEMBERS
- EndpointGroupsRemoveMembersOperation
EndpointGroupsRemoveMembersOperation Removes endpoint members from a group. IDs that are not members are ignored.
Selected when operation is REMOVE_MEMBERS
- EndpointGroupsMergeIntoOperation
EndpointGroupsMergeIntoOperation Merges source groups into a target group. Source group routes are rehomed to the target, memberships are unioned, and each source ID becomes a redirect to the target. Identity decision that requires explicit user confirmation.
Selected when operation is MERGE_INTO
- EndpointGroupsSetEnablementOperation
EndpointGroupsSetEnablementOperation Enables or disables a group. A disabled group is hidden from group lists by default and cannot be targeted by messages such as clean-room. Rediscovery never re-enables it, so disabling (not deleting) is how a user hides a discovered group, such as a robot's room, for good.
Selected when operation is SET_ENABLEMENT
- requestId
stringRequired Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.
minLength: 1
maxLength: 64
- etag
stringRequired The group etag the client last read. When an earlier operation in the same request changes this group, send the etag that operation reports instead: every operation that changes the group advances its etag by one.
minLength: 1
- enablement
stringRequired Whether Port OS uses an endpoint or group. A disabled one is hidden from collections by default and cannot be sent device messages or targeted by them; exact authorized reads still return it. Rediscovery never changes it, so disabling is how a user hides a discovered device or room for good.
Default:
ENABLEDAllowed values: ENABLED, DISABLED.
- requestId
- EndpointGroupsCreateGroupOperation
Result
Fields
- status
stringRequired Outcome of an atomic batch. `COMMITTED` means every operation was applied (or, for a validate-only request, would be applied); `FAILED` means nothing was written and `errors` lists every failing operation.
Allowed values: COMMITTED, FAILED.
- results
array<EndpointGroupsManageResult>Required Result of one committed operation, correlated by `requestId`. `CREATE_GROUP`, `SET_NAME`, `ADD_MEMBERS` and `REMOVE_MEMBERS` return `group` with its new etag; `DELETE_GROUP` returns `deletedGroupId`; `MERGE_INTO` returns `target` with its new etag and `redirects`.
- requestId
stringRequired Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.
minLength: 1
maxLength: 64
- operation
stringRequired Discriminator of an endpoint group management operation.
Allowed values: CREATE_GROUP, DELETE_GROUP, SET_NAME, ADD_MEMBERS, REMOVE_MEMBERS, MERGE_INTO, SET_ENABLEMENT.
- group
EndpointGroupEtagReference A group addressed together with the etag the client last read, validated inside the management transaction.
- requestId
- errors
array<BatchItemError>Required Error for one operation of an atomic batch, correlated by the operation's `requestId`. `status` is the HTTP status the operation would have returned on its own.
- requestId
stringRequired Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.
minLength: 1
maxLength: 64
- code
stringRequired 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.
Allowed values: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, INSUFFICIENT_SCOPE, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, UNSUPPORTED_OPERATION, TOO_MANY_REQUESTS, SERVICE_UNAVAILABLE, NOT_IMPLEMENTED, INTERNAL, CHECKSUM_MISMATCH, FILE_TOO_LARGE, STORAGE_UNAVAILABLE, INSUFFICIENT_PERMISSIONS, INVALID_FILE_TYPE, QUOTA_EXCEEDED, CONCURRENT_MODIFICATION, ENDPOINT_UNREACHABLE, BRIDGE_UNREACHABLE, CLOUD_CONTROL_DISABLED, ENDPOINT_BUSY, ENDPOINT_LOW_POWER, AUTHORIZATION_CREDENTIAL_INVALID, AUTHORIZATION_CREDENTIAL_EXPIRED, INVALID_DIRECTIVE, INVALID_VALUE, VALUE_OUT_OF_RANGE, NOT_SUPPORTED_IN_CURRENT_MODE, RATE_LIMIT_EXCEEDED, PROVIDER_SERVICE_UNAVAILABLE, PROVIDER_TIMEOUT, PROVIDER_INTERNAL_ERROR, INVALID_PROVIDER_RESPONSE, OUTCOME_UNKNOWN, PRECONDITION_FAILED, AUTH_LINK_NOT_READY, AUTH_LINK_NOT_DISCONNECTABLE, PRECONDITION_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_FLIGHT, IDEMPOTENCY_KEY_INVALID, GROUP_MERGED, MULTI_ROOM_UNSUPPORTED, MAP_NOT_ACTIVE, TARGET_UNSUPPORTED, TARGET_AMBIGUOUS, TARGET_GROUP_NOT_FOUND, TARGET_GROUP_DISABLED, DUPLICATE_TARGET_GROUP, MESSAGE_UNSUPPORTED, MESSAGE_AMBIGUOUS, ENDPOINT_DISABLED, ENDPOINT_ROUTE_CHANGED, ENDPOINT_HAS_DEPENDENCIES, ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE, ENDPOINT_COMMITTED_CLEANUP_PENDING, DEEP_QUERY_FAILED, PROVIDER_NO_STATE, EVENT_MANAGEMENT_DISABLED, SUBSCRIPTION_IDENTITY_IMMUTABLE, UNSUPPORTED_MEDIA_TYPE, EVENT_PAYLOAD_TOO_LARGE, REQUEST_BODY_TOO_LARGE, EVENT_IDENTITY_CONFLICT, EVENT_INGRESS_QUOTA_EXCEEDED, EVENT_RECEIPT_EXPIRED, EVENT_STORAGE_UNAVAILABLE, EVENT_DEAD_LETTER_NOT_FOUND, EVENT_REDRIVE_CONFLICT, EVENT_REDRIVE_EXPIRED, RECEIPT_CONTEXT_EXPIRED, EVENT_MAINTENANCE_INCOMPLETE, UNKNOWN_INTERFACE, INVALID_CONFIGURATION, INVALID_ATTRIBUTE, INVALID_PROVIDER_MESSAGE, UNDECLARED_CAPABILITY, PLUGIN_ROUTE_ID_CONFLICT, UNRESOLVED_REFERENCE, INVALID_RELATIONSHIP, RELATIONSHIP_CYCLE, MULTIPLE_PARENTS, FLOW_VALIDATION_FAILED.
- family
stringRequired 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.
Allowed values: NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, CONFLICT, GONE, PRECONDITION_FAILED, PRECONDITION_REQUIRED, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, UNPROCESSABLE_ENTITY, LOCKED, TOO_MANY_REQUESTS, BAD_GATEWAY, SERVICE_UNAVAILABLE, GATEWAY_TIMEOUT, NOT_IMPLEMENTED, INTERNAL_SERVER_ERROR, REQUEST_INVALID, AUTHENTICATION, PERMISSION, ENDPOINT_NOT_FOUND, ENDPOINT_STATE_CONFLICT, ENDPOINT_UNAVAILABLE, RATE_LIMIT, PROVIDER_BAD_RESPONSE, PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT.
- requestId
Errors
A failed call returns this error object as its result instead.
Fields
- family
stringRequired 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.
Allowed values: NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, CONFLICT, GONE, PRECONDITION_FAILED, PRECONDITION_REQUIRED, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, UNPROCESSABLE_ENTITY, LOCKED, TOO_MANY_REQUESTS, BAD_GATEWAY, SERVICE_UNAVAILABLE, GATEWAY_TIMEOUT, NOT_IMPLEMENTED, INTERNAL_SERVER_ERROR, REQUEST_INVALID, AUTHENTICATION, PERMISSION, ENDPOINT_NOT_FOUND, ENDPOINT_STATE_CONFLICT, ENDPOINT_UNAVAILABLE, RATE_LIMIT, PROVIDER_BAD_RESPONSE, PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT.
- code
stringRequired 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.
Allowed values: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, INSUFFICIENT_SCOPE, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, UNSUPPORTED_OPERATION, TOO_MANY_REQUESTS, SERVICE_UNAVAILABLE, NOT_IMPLEMENTED, INTERNAL, CHECKSUM_MISMATCH, FILE_TOO_LARGE, STORAGE_UNAVAILABLE, INSUFFICIENT_PERMISSIONS, INVALID_FILE_TYPE, QUOTA_EXCEEDED, CONCURRENT_MODIFICATION, ENDPOINT_UNREACHABLE, BRIDGE_UNREACHABLE, CLOUD_CONTROL_DISABLED, ENDPOINT_BUSY, ENDPOINT_LOW_POWER, AUTHORIZATION_CREDENTIAL_INVALID, AUTHORIZATION_CREDENTIAL_EXPIRED, INVALID_DIRECTIVE, INVALID_VALUE, VALUE_OUT_OF_RANGE, NOT_SUPPORTED_IN_CURRENT_MODE, RATE_LIMIT_EXCEEDED, PROVIDER_SERVICE_UNAVAILABLE, PROVIDER_TIMEOUT, PROVIDER_INTERNAL_ERROR, INVALID_PROVIDER_RESPONSE, OUTCOME_UNKNOWN, PRECONDITION_FAILED, AUTH_LINK_NOT_READY, AUTH_LINK_NOT_DISCONNECTABLE, PRECONDITION_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_FLIGHT, IDEMPOTENCY_KEY_INVALID, GROUP_MERGED, MULTI_ROOM_UNSUPPORTED, MAP_NOT_ACTIVE, TARGET_UNSUPPORTED, TARGET_AMBIGUOUS, TARGET_GROUP_NOT_FOUND, TARGET_GROUP_DISABLED, DUPLICATE_TARGET_GROUP, MESSAGE_UNSUPPORTED, MESSAGE_AMBIGUOUS, ENDPOINT_DISABLED, ENDPOINT_ROUTE_CHANGED, ENDPOINT_HAS_DEPENDENCIES, ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE, ENDPOINT_COMMITTED_CLEANUP_PENDING, DEEP_QUERY_FAILED, PROVIDER_NO_STATE, EVENT_MANAGEMENT_DISABLED, SUBSCRIPTION_IDENTITY_IMMUTABLE, UNSUPPORTED_MEDIA_TYPE, EVENT_PAYLOAD_TOO_LARGE, REQUEST_BODY_TOO_LARGE, EVENT_IDENTITY_CONFLICT, EVENT_INGRESS_QUOTA_EXCEEDED, EVENT_RECEIPT_EXPIRED, EVENT_STORAGE_UNAVAILABLE, EVENT_DEAD_LETTER_NOT_FOUND, EVENT_REDRIVE_CONFLICT, EVENT_REDRIVE_EXPIRED, RECEIPT_CONTEXT_EXPIRED, EVENT_MAINTENANCE_INCOMPLETE, UNKNOWN_INTERFACE, INVALID_CONFIGURATION, INVALID_ATTRIBUTE, INVALID_PROVIDER_MESSAGE, UNDECLARED_CAPABILITY, PLUGIN_ROUTE_ID_CONFLICT, UNRESOLVED_REFERENCE, INVALID_RELATIONSHIP, RELATIONSHIP_CYCLE, MULTIPLE_PARENTS, FLOW_VALIDATION_FAILED.
- details
ErrorDetails Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.
- discoveryEndpointId
string Port OS provider endpoint (type ENDPOINT_PLUGIN) of the connection to send `discover-routes` to when `code` is `TARGET_UNSUPPORTED` because the route must be rediscovered.
- retryAfterSeconds
integer Suggested retry delay for rate-limit or provider-unavailable failures.
minimum: 0
- providerCode
string The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.
- discoveryEndpointId
- errors
array<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.
One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.
- pluginRouteId
string Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.
- relationshipExternalId
string Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.
- interface
string Canonical capability interface name the failure applies to, when the failure is interface-specific.
- version
string Declared capability interface version the failure applies to, when the failure is interface-specific.
- code
stringRequired 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.
Allowed values: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, INSUFFICIENT_SCOPE, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, UNSUPPORTED_OPERATION, TOO_MANY_REQUESTS, SERVICE_UNAVAILABLE, NOT_IMPLEMENTED, INTERNAL, CHECKSUM_MISMATCH, FILE_TOO_LARGE, STORAGE_UNAVAILABLE, INSUFFICIENT_PERMISSIONS, INVALID_FILE_TYPE, QUOTA_EXCEEDED, CONCURRENT_MODIFICATION, ENDPOINT_UNREACHABLE, BRIDGE_UNREACHABLE, CLOUD_CONTROL_DISABLED, ENDPOINT_BUSY, ENDPOINT_LOW_POWER, AUTHORIZATION_CREDENTIAL_INVALID, AUTHORIZATION_CREDENTIAL_EXPIRED, INVALID_DIRECTIVE, INVALID_VALUE, VALUE_OUT_OF_RANGE, NOT_SUPPORTED_IN_CURRENT_MODE, RATE_LIMIT_EXCEEDED, PROVIDER_SERVICE_UNAVAILABLE, PROVIDER_TIMEOUT, PROVIDER_INTERNAL_ERROR, INVALID_PROVIDER_RESPONSE, OUTCOME_UNKNOWN, PRECONDITION_FAILED, AUTH_LINK_NOT_READY, AUTH_LINK_NOT_DISCONNECTABLE, PRECONDITION_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_FLIGHT, IDEMPOTENCY_KEY_INVALID, GROUP_MERGED, MULTI_ROOM_UNSUPPORTED, MAP_NOT_ACTIVE, TARGET_UNSUPPORTED, TARGET_AMBIGUOUS, TARGET_GROUP_NOT_FOUND, TARGET_GROUP_DISABLED, DUPLICATE_TARGET_GROUP, MESSAGE_UNSUPPORTED, MESSAGE_AMBIGUOUS, ENDPOINT_DISABLED, ENDPOINT_ROUTE_CHANGED, ENDPOINT_HAS_DEPENDENCIES, ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE, ENDPOINT_COMMITTED_CLEANUP_PENDING, DEEP_QUERY_FAILED, PROVIDER_NO_STATE, EVENT_MANAGEMENT_DISABLED, SUBSCRIPTION_IDENTITY_IMMUTABLE, UNSUPPORTED_MEDIA_TYPE, EVENT_PAYLOAD_TOO_LARGE, REQUEST_BODY_TOO_LARGE, EVENT_IDENTITY_CONFLICT, EVENT_INGRESS_QUOTA_EXCEEDED, EVENT_RECEIPT_EXPIRED, EVENT_STORAGE_UNAVAILABLE, EVENT_DEAD_LETTER_NOT_FOUND, EVENT_REDRIVE_CONFLICT, EVENT_REDRIVE_EXPIRED, RECEIPT_CONTEXT_EXPIRED, EVENT_MAINTENANCE_INCOMPLETE, UNKNOWN_INTERFACE, INVALID_CONFIGURATION, INVALID_ATTRIBUTE, INVALID_PROVIDER_MESSAGE, UNDECLARED_CAPABILITY, PLUGIN_ROUTE_ID_CONFLICT, UNRESOLVED_REFERENCE, INVALID_RELATIONSHIP, RELATIONSHIP_CYCLE, MULTIPLE_PARENTS, FLOW_VALIDATION_FAILED.
- family
stringRequired 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.
Allowed values: NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, CONFLICT, GONE, PRECONDITION_FAILED, PRECONDITION_REQUIRED, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, UNPROCESSABLE_ENTITY, LOCKED, TOO_MANY_REQUESTS, BAD_GATEWAY, SERVICE_UNAVAILABLE, GATEWAY_TIMEOUT, NOT_IMPLEMENTED, INTERNAL_SERVER_ERROR, REQUEST_INVALID, AUTHENTICATION, PERMISSION, ENDPOINT_NOT_FOUND, ENDPOINT_STATE_CONFLICT, ENDPOINT_UNAVAILABLE, RATE_LIMIT, PROVIDER_BAD_RESPONSE, PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT.
- pluginRouteId