List Devices and Health Summary APIs

Knowledge Base > Products > Software > Loop Cloud > List Devices and Health Summary APIs

List Device Types

Overview

List the schemas for available device types. These describe the schema (properties and configurations) of each device type and provides the unique id (x-id) for subsequent API requests for a specific device type.

Get Object Types
API Request Overview

 

Endpoint

https://api.us.loop.bluecats.com/schemas/objectTypes

Method

GET

Pagination Type

limit, offset

Description

List the schema of Loop dynamic objects

Headers

 
authorization: Bearer {access_token}
bc-loop-orgid: bc000000-a1a1-b2b2-c3c3-d4d4e5e5f6

Example Query

 
https://api.us.loop.bluecats.com/schemas/objectTypes
 
request parameters

Key

Attributes

Description

limit

Optional
default 100
max 500
Int

Maximum number of results to return

offset

Optional
default 0
Int

Offset results when paging
 
Example Response Body

 

GET schema/objectTypes

{"items": [{"x-id": "00000000-0000-0000-0000-a1beb5b30024","x-orgId": "00000000-0000-0000-0000-000000000000","title": "BC4520 ProxPoint","description": "BC4520","required": ["name","mac"],"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000","x-stereotypes": ["device"],"x-settings": {"titleFormat": "{$.name.value}","descriptionFormat": "{$.mac.value}","modelNumber": "BC4520","systemManaged": false,"registerMac": true,"list": ["name","mac","installedInPlace","monitoredUptime"],"form": ["name","mac","installedInPlace","installedAtPosition","monitoredUptime","trackedPosition"],"metrics": ["Connectivity","DeviceReboot"]},"properties": {"name": {"title": "Name","x-reference": true,"x-unique": false,"x-propertyType": "string","readOnly": false,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"mac": {"title": "MAC Address","x-reference": true,"x-unique": true,"x-propertyType": "deviceIdentifier","readOnly": false,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"installedInPlace": {"title": "Installed Location","x-reference": true,"x-unique": false,"x-propertyType": "association","readOnly": false,"enum": [],"x-associatedObjectTypes": ["00000000-0000-0000-0000-a1beb5b30001","00000000-0000-0000-0000-a1beb5b30002","00000000-0000-0000-0000-a1beb5b30000"],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"installedAtPosition": {"title": "Installed Position","x-reference": true,"x-unique": false,"x-propertyType": "position","readOnly": false,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"monitoredUptime": {"title": "Uptime","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"trackedPosition": {"title": "Position","x-reference": false,"x-unique": false,"x-propertyType": "position","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"}}},{"x-id": "00000000-0000-0000-0000-a1beb5b30008","x-orgId": "00000000-0000-0000-0000-000000000000","title": "BC2611 Safety Tag","description": "BC2611","required": ["name","mac"],"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000","x-stereotypes": ["device"],"x-settings": {"titleFormat": "{$.name.value}","descriptionFormat": "{$.mac.value}","modelNumber": "BC2611","systemManaged": false,"registerMac": false,"list": ["name","mac","assignedTo","monitoredUptime","monitoredBatteryPercentage","trackedPlace","trackedSite"],"form": ["name","mac","assignedTo","monitoredUptime","monitoredBatteryPercentage","monitoredBatteryVoltage","monitoredTemperature","trackedPlace","trackedSite","trackedPosition","distanceFromPlace","locationSource"],"metrics": ["BatteryPercentage","LastSeen"]},"properties": {"name": {"title": "Name","x-reference": true,"x-unique": false,"x-propertyType": "string","readOnly": false,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"mac": {"title": "MAC Address","x-reference": true,"x-unique": true,"x-propertyType": "deviceIdentifier","readOnly": false,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"assignedTo": {"title": "Assigned To","x-reference": true,"x-unique": false,"x-propertyType": "association","readOnly": false,"enum": [],"x-associatedObjectTypes": ["00000000-0000-0000-0000-a1beb5b30005"],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"monitoredUptime": {"title": "Uptime","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"monitoredBatteryPercentage": {"title": "Battery %","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"monitoredBatteryVoltage": {"title": "Battery Voltage","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"monitoredTemperature": {"title": "Temperature","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"trackedPlace": {"title": "Location","x-reference": false,"x-unique": false,"x-propertyType": "association","readOnly": true,"enum": [],"x-associatedObjectTypes": ["00000000-0000-0000-0000-a1beb5b30000","00000000-0000-0000-0000-a1beb5b30001","00000000-0000-0000-0000-a1beb5b30002"],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"trackedSite": {"title": "Site","x-reference": false,"x-unique": false,"x-propertyType": "association","readOnly": true,"enum": [],"x-associatedObjectTypes": ["00000000-0000-0000-0000-a1beb5b30000"],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"trackedPosition": {"title": "Position","x-reference": false,"x-unique": false,"x-propertyType": "position","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"distanceFromPlace": {"title": "Distance from Zone","x-reference": false,"x-unique": false,"x-propertyType": "telemetry","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"},"locationSource": {"title": "Location Source","x-reference": false,"x-unique": false,"x-propertyType": "string","readOnly": true,"enum": [],"x-associatedObjectTypes": [],"x-previousVersions": 0,"x-createdAt": "0001-01-01T00:00:00+00:00","x-createdBy": "00000000-0000-0000-0000-000000000000"}}}...additional results truncated]
}

Device Health Summary by Type

Overview

The device health dashboard (https://app.us.loop.bluecats.com/management/dashboard ) provides a summary of key metrics for each device type. This API provides relevant metrics for each device type, grouped by value and segregated by devices recently observed within a specified time, or the last known value for devices observed before that time.

Get Metric Summary by Device Type
API Request Overview

 

Endpoint https://api.us.loop.bluecats.com/summaryMetrics/objects

Method

GET

Pagination Type

NA

Description

List of available metrics and counts of devices grouped by value

Headers

 
authorization: Bearer {access_token}
bc-loop-orgid: bc000000-a1a1-b2b2-c3c3-d4d4e5e5f6

Example Query

 
https://api.us.loop.bluecats.com/summaryMetrics/objects
?stereotype=Device
&objectTypeId=00000000-0000-0000-0000-000000000000
&staleObservationsSeconds=86400
Request Parameters

Key

Attributes

Description

stereotype

Required
String (enumeration Device, Asset, Person, Place)

Type super type of the requested object type. Set as Device for device metrics.

objectTypeId

Required
String (uuid)

The unique id of an object type. This is the x-id field obtained from the above GET /schemas/objectTypes API.

staleObservationSeconds

Optional
Default 604800 (1 week)
Int

Counts are provided grouped by the last known value of a given metric. These groupings are split into two further groups for devices observed before and after the provided number of seconds from the current time. This is so stale results for devices that have not been observed for a period of time can be excluded from the results e.g. ‘Show all of devices with low battery that have been observed in the last 24 hours’ (staleObservationSeconds=86400)
Example Response Body
GET summaryMetrics/objects

[{"metric": "Connectivity","property": "monitoredUptime","title": "Connectivity","description": "Device is Offline if it has not recently been detected or sent data to the server","objectTypeId": "00000000-0000-0000-0000-000000000000","total": 2,"staleSeconds": 86400,"values": [{"title": "Online","value": "Good","stale": false,"count": 1},{"title": "Offline","value": "Poor","stale": false,"count": 0},{"title": "Offline","value": "Poor","stale": true,"count": 0},{"title": "Never reported","value": "Unknown","stale": false,"count": 1}]},{"metric": "DeviceReboot","property": "monitoredUptime","title": "Device Reboot","description": "Device has Rebooted if its uptime has reset within the selected period","objectTypeId": "00000000-0000-0000-0000-000000000000","total": 2,"staleSeconds": 86400,"values": [{"title": "Running continuously","value": "Good","stale": false,"count": 1},{"title": "Running continuously","value": "Good","stale": true,"count": 0},{"title": "Rebooted","value": "Fair","stale": false,"count": 0},{"title": "Rebooted","value": "Fair","stale": true,"count": 0},{"title": "Never reported","value": "Unknown","stale": false,"count": 1}]}
]

List Devices

Overview

 List the schemas for available device types. These describe the schema (properties and configurations) of each device type and provides the unique id (x-id) for subsequent API requests for a specific device type.

Get Objects
API Request Overview

 

Endpoint

https://api.us.loop.bluecats.com/objects

Method

GET

Pagination Type

limit, offset

Description

List objects by type

Headers

 
authorization: Bearer {access_token}
bc-loop-orgid: bc000000-a1a1-b2b2-c3c3-d4d4e5e5f6

Example Query

 
https://api.us.loop.bluecats.com/objects
?objectTypeId=00000000-0000-0000-0000-000000000000
&limit=10&metricFilter=BatteryPercentage
&metricValue=Good
&metricStale=false
&staleObservationsSeconds=86400
request parameters

The following request parameters can be used to list all devices of a requested type.

Key

Attributes

Description

objectTypeId

Required
String (uuid)

The unique id of an object type. This is the x-id field obtained from the above GET /schemas/objectTypes API.

limit

Optional
default 100
max 500
Int

Maximum number of results to return

offset

Optional
default 0
Int

Offset results when paging

The following additional optional parameters may be included to filter devices based on a specific metric value using the results from the /summaryMetrics/objects request e.g. to list all devices with low battery observed in the last 24 hours.

Key

Attributes

Description

metricFilter

Optional
string (enum)

Metric Filter enumeration obtained from /summaryMetrics/objects request

metricValue

Optional
string(enum Good, Fair, Poor)

Metric Value enumeration obtained from /summaryMetrics/objects request

metricStale

Optional

Filter for the given metric value where last known observation is before (metricStale=true) or after (metricStale=false) the given number of seconds (staleObservationSeconds) ago

staleObservationSeconds

Optional
Default 604800 (1 week)
Int

Number of seconds before the last known value for the metric is considered stale.
example response body
GET /objects
{"items": [{"id": "00000000-0000-0000-0000-000000000000","groupId": "00000000-0000-0000-0000-000000000000","orgId": "00000000-0000-0000-0000-000000000000","objectTypeId": "00000000-0000-0000-0000-000000000000","stereotype": "device","title": "D42500112233","description": "D42500112233","updatedAt": "2021-08-04T04:43:32Z","createdAt": "2021-07-30T00:03:08Z","deletedAt": null,"createdBy": "00000000-0000-0000-0000-000000000000","updatedBy": "00000000-0000-0000-0000-000000000000","deletedBy": "None","assignedTo": {"value": null,"observedAt": "2021-08-04T04:43:33Z","changedAt": "2021-08-04T04:43:33Z","updatedAt": "2021-08-04T04:43:33Z"},"mac": {"value": "D42500112233","observedAt": null,"changedAt": null,"updatedAt": "2021-07-30T02:43:46Z"},"monitoredBatteryPercentage": {"value": 100.0,"observedAt": "2021-08-17T12:59:30Z","changedAt": null,"updatedAt": "2021-08-17T13:15:28Z"},"monitoredBatteryVoltage": {"value": 4214.17,"observedAt": "2021-08-17T12:59:29Z","changedAt": "2021-08-17T12:59:29Z","updatedAt": "2021-08-17T13:15:27Z"},"monitoredTemp": {"value": 23.20114299229213,"observedAt": "2021-08-12T05:21:22Z","changedAt": "2021-08-12T05:21:22Z","updatedAt": "2021-08-12T05:45:18Z"},"monitoredUptime": {"value": 544974.0,"observedAt": "2021-08-17T12:59:29Z","changedAt": "2021-08-17T12:59:29Z","updatedAt": "2021-08-17T13:15:29Z"},"name": {"value": "D42500112233","observedAt": null,"changedAt": null,"updatedAt": "2021-08-02T00:21:35Z"}},...additional results truncated],"offset": 0,"limit": 10,"total": 10
}

Navigation