Skip to content

Minor updates to Endpoint API

Sorting endpoints

We have now added the ability to sort endpoints when listing them.

GET /endpoint/v1/endpoints?sort=<key>:<direction>

Here, <key> must be specified and must be one of:

  • type: the endpoint type (computer/server)
  • lastSeenAt: the date and time when the endpoint last communicated with Central
  • macAddresses: the physical network address
  • tamperProtection: whether tamperProtection is enabled or not
  • healthStatus: the overall health status

Specifying <direction> is optional. It can be asc or desc. If you don't supply it, the default assumed value of <direction> varies from field to field.

As an example, you could sort endpoints by healthStatus like so:

GET /endpoint/v1/endpoints?sort=healthStatus

Alternatively, you can specify the sort direction:

GET /endpoint/v1/endpoints?sort=healthStatus:desc

When the sort query parameter is not supplied, the results may not be sorted.

Richer filtering of endpoints

You can now filter the list of endpoints, matching endpoint fields against multiple comma-separated values.

Find endpoints with specific IDs:

GET /endpoint/v1/endpoints?ids=15951e01-39e5-4cb3-8508-63a6086b01bb,4f656c27-59ba-4921-a5de-9db2dd967e31,08841f43-ca1f-433b-bbbe-6bd24864c9d8

Find endpoints that aren't healthy:

GET /endpoint/v1/endpoints?healthStatus=suspicious,bad

Find servers or security VMs:

GET /endpoint/v1/endpoints?type=server,securityVm

Find servers where LockDown is not installed or the server is unlocked or the status is unavailable:

GET /endpoint/v1/endpoints?type=server&lockdownStatus=notInstalled,unlocked,unavailable

You can supply multiple filters as in the example above. As before, only endpoints matching all the filters will be returned.

Additional endpoint information

The endpoint object in responses returned by the Endpoint API now contains more information:

  • The group field shows the name of the group the endpoint belongs to. (Note that there is no API to manage endpoint groups at this time.)
  • Each item in the assignedProducts array now indicates whether the installation status of the product: installed or notInstalled.

Count of matching endpoints

When you pass pageTotal=true to a paginated API that returns endpoint objects, the pages object in the response now additionally contains the total number of matching endpoints across all pages.

For instance, the API call:

GET /endpoint/v1/endpoints?type=server&pageTotal=true

... returns a single page of server endpoints that looks like:

{
  "items": [
    { "id": "6e106c79-3441-4c22-826a-47761e289a41", "type": "server", ... },
    { "id": "be950351-024e-4a10-bac3-049d89ef3dfe", "type": "server", ... },
    ...
  ],
  "pages": {
    "nextKey": "<...a long pagination key...>",
    "size": 50,
    "maxSize": 500,
    "total": 4,       // The number of pages of endpoints
    "items": 195      // The total number of endpoints across all pages
  }
}