Device List Request

The DeviceListRequest retrieves the devices that are visible to your customer account. A device is any FlexCloud-managed hardware unit — RapidNodes or FlexNodes — identified by one or more identifiers, and enriched with a product/firmware description plus optional groups, tags, attributes, and permissions.

Typical use cases:

• Discovering the SKI (or other) identifiers of your devices before using them in requests such as NodeStateListRequest or NodeControlPowerScheduleModifyRequest.
• Filtering the fleet by product type (batteries, meters, …), model, variant, or firmware release.
• Selecting devices that belong to a specific group or carry a specific tag/attribute value.

Preparations

• Launch the development client as described in the FlexConnect API — First Steps.
• Navigate to http://localhost:8080/ui.
• Select the documentation for Device List Request in the left pane.

Request

Run the DeviceListRequest using the JSON body below.

1. Run the request on app/v1/DeviceListRequest.
2. Set pagination.limit to the number of devices you want returned per page.
3. Choose the detailTypes you actually need — smaller lists produce smaller responses.
4. Optionally, narrow the result set with filter. Leave all filter arrays empty ([]) to retrieve every device visible to your authentication.

Request body

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "pagination": {
    "limit": 100
  },
  "filter": {
    "ids": [],
    "productTypeIds": [],
    "productModelIds": [],
    "productVariantIds": [],
    "firmwareReleaseIds": [],
    "firmwareDeploymentGroupIds": [],
    "groups": [],
    "tags": [],
    "attributes": []
  },
  "detailTypes": [3, 5]
}

The example above lists all devices visible to the caller and includes the device identifiers (IDS = 3) and the group memberships (GROUPS = 5) for each device. Product, firmware, tags, attributes, permissions, and names are omitted from the response because their detail types are not requested.

Request fields

Field	Description
header.reqId	Client-defined identifier for the request. The same value is returned in the response header to correlate requests and responses.
header.timeoutMs	Maximum time (in milliseconds) the platform waits for the result before responding with a timeout error.
pagination.limit	Maximum number of devices returned in a single response.
pagination.cursorValue	Cursor value returned in a previous response as cursorNext or cursorPrevious. Use it to iterate through large result sets.
filter.ids	If non-empty, only devices carrying one of these identifiers are returned. Useful when you want to look up a specific known device by id.
filter.productTypeIds	If non-empty, only devices of these product types are returned. See productTypeIds values.
filter.productModelIds	If non-empty, only devices of these product models are returned.
filter.productVariantIds	If non-empty, only devices of these product variants are returned.
filter.firmwareReleaseIds	If non-empty, only devices currently running one of these firmware releases are returned.
filter.firmwareDeploymentGroupIds	If non-empty, only devices assigned to one of these firmware deployment groups are returned.
filter.groups	If non-empty, only devices that are members of at least one of these groups are returned. Reference groups by id — see GroupListRequest.
filter.tags	If non-empty, only devices tagged with at least one of these tags are returned.
filter.attributes	If non-empty, only devices with matching attribute id and value are returned.
detailTypes	List of optional detail types to include for each device. See detailTypes values.

detailTypes values

Value	Code	Description
1	ATTRIBUTES	Include the attributes list for each device.
2	TAGS	Include the tags list for each device.
3	IDS	Include the ids list for each device (the actual device identifiers — typically the SKI).
4	FIRMWARE	Include the firmware block for each device (firmwareReleaseId, firmwareDeploymentGroupId).
5	GROUPS	Include the groups list for each device.
6	PERMISSIONS	Include the permissions list for each device.
7	NAMES	Include the human-readable names of groups, tags, and attributes in the response (otherwise only the ids are returned).

Request only what you need

Detail types are additive — request the union of what you actually need. For an inventory list, IDS (3) and PRODUCT information are often enough. To render labels in a UI, include NAMES (7) so groups, tags, and attributes come back with their names populated.

productTypeIds values

Value	Code	Description
1	BATTERY	Battery.
2	METER	Meter.
3	RASPIBRIDGE	Raspberry-Pi based bridge.
4	ETHERBRIDGE	Ethernet bridge.
5	RAPIDNODE	RapidNode.
6	FLEXNODE	FlexNode.

Response

Response body

{
  "header": {
    "reqId": 1234
  },
  "pagination": {
    "cursorNext": "AADF=",
    "cursorPrevious": "AABC="
  },
  "devices": [
    {
      "ids": [
        {
          "type": { "id": 2 },
          "stringValue": "609FE0C1B6F4A36E561A7FD061C6554191E6E393"
        }
      ],
      "groups": [{ "id": 1 }]
    }
  ]
}

The response contains only the detail types requested in detailTypes. In the example above only IDS (3) and GROUPS (5) were requested, so the entries in devices carry ids and groups but not product, firmware, tags, attributes, or permissions. Adding those detail types to the request expands each entry accordingly:

{
  "ids": [{ "type": { "id": 2 }, "stringValue": "609FE0C1B6F4A36E561A7FD061C6554191E6E393" }],
  "product": {
    "productModelId": 2,
    "productTypeId": 1,
    "productVariantId": 2
  },
  "firmware": {
    "firmwareReleaseId": 1,
    "firmwareDeploymentGroupId": 1
  },
  "groups": [{ "id": 1, "name": "FHE internal groups" }],
  "tags": [{ "id": 1, "name": "Pilot" }],
  "attributes": [{ "id": 1, "name": "installation-date", "value": "2026-01-01" }],
  "permissions": [{ "permissionTypeId": 1, "permissionCodeId": 1 }]
}

Response fields

Field	Description
devices[].ids	Identifiers of the device. Included when detailTypes contains 3 (IDS). Use one of these values (typically the SKI) in deviceId / filter.ids of other requests.
devices[].product	Product model, type, and variant of the device. Always populated in the response.
devices[].firmware	Firmware release and deployment group the device is running. Included when detailTypes contains 4 (FIRMWARE). A value of 0 means the platform does not know the firmware, or that the device is not assigned to a firmware deployment group.
devices[].groups	Groups the device belongs to. Included when detailTypes contains 5 (GROUPS). Names are only populated when detailTypes also includes 7 (NAMES).
devices[].tags	Tags associated with the device. Included when detailTypes contains 2 (TAGS). Names are only populated when detailTypes also includes 7 (NAMES).
devices[].attributes	Additional key/value metadata attached to the device. Included when detailTypes contains 1 (ATTRIBUTES). Names are only populated when detailTypes also includes 7 (NAMES).
devices[].permissions	Permissions your authentication has on this device. Included when detailTypes contains 6 (PERMISSIONS).
pagination.cursorNext / cursorPrevious	Returned when the result set is larger than limit. Pass either value as pagination.cursorValue in a follow-up request to paginate.

Pagination

When the number of matching devices exceeds pagination.limit, the response includes a pagination.cursorNext value (and a cursorPrevious value when iterating). Pass either value as pagination.cursorValue in a follow-up request — keeping filter and detailTypes unchanged — to retrieve the next or previous page. Iteration ends when no further cursor is returned.

Use groups to scope other requests

Use GroupListRequest to discover the ids of the groups your devices belong to. You can then pass those ids in filter.groups here — or in filter.groups of other list requests — to scope a query to a specific subset of your fleet.