Get an endpoint group

← HTTP API reference

View source specification ↗

GET /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}

Get an endpoint group by ID.

Required scope

group:read

Path parameters

namespacestringRequired: The namespace of the principal
principalTypestringRequired: The type of principal
principalIdstringRequired: The ID of the principal
groupIdstringRequired: The ID of the endpoint group to retrieve

Query parameters

expandarray<string>

Expansion tokens that request related or computed fields for the returned resource. Use `interfaces.attributes` to populate the group's `attributes` array with the stored values of its group routes.

forceDeviceAttributeQueryboolean

Asks each provider for fresh values of the group routes before the response is returned. Only applied when `expand` includes `interfaces.attributes`. Absent, invalid or `false` values return the stored values. A forced read includes only attributes refreshed by that request. If a provider cannot be reached or rejects the request, the request returns `500 DEEP_QUERY_FAILED` instead of presenting stored values as fresh. If a provider answers but gives no value for a declared attribute, that attribute is returned without a `value` and with an `error` whose code is `PROVIDER_NO_STATE`; the request still succeeds.

Returns

200

Endpoint group retrieved successfully

Fields

idstringRequired

The unique identifier for the endpoint group

pattern: "^port1/[^/]+/[^/]+/endpoint-groups/[^/]+$"

nameTypeValueRequired

The name of the endpoint group

ownerIdstringRequired

The ID of the owner of the endpoint group

enablementstringRequired

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: ENABLED

Allowed values: ENABLED, DISABLED.

memberEndpointIdsarray<string>

List of member endpoint IDs of the endpoint group

interfacesarray<ApplicationInterface>Required

List of interfaces supported by the endpoint group

etagstringRequired

Opaque strong entity tag of this group version, for example `"12"`. It changes on any committed write to the group, its group routes or its relationships. Send it as `If-Match` (or as the operation `etag` in `/endpoint-groups-manage`) when mutating the group.

redirectedFromstring

Set when the group was read through a merged-away ID: the ID that was requested, which now redirects to this group. Mutations must use this group's `id`.

parentGroupIdstring

The canonical parent group derived from `IS_PART_OF` relationships, when the group has one.

childGroupIdsarray<string>

Canonical child groups derived from `IS_PART_OF` relationships.

controllersarray<EndpointGroupController>

Endpoints that declare `CAN_CONTROL` on one of this group's group routes, with the messages they support on it.

attributesarray<GroupRouteAttributeState>

The group's state: every attribute value stored for its group routes, one entry per group route and attribute, tagged with the group route and provider. Populated only when the read is called with `expand=interfaces.attributes`.

Response headers

ETagstring: Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.

Errors

400 BAD_REQUEST

Invalid request payload

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Forbidden - insufficient permissions

Check the linked account and its permissions for the device or resource.

404 NOT_FOUND

Endpoint group not found

Verify the target identifier and that its endpoint or plugin route still exists.

500 INTERNAL

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.