Skip to content

Guide — Endpoint Groups Management

Overview

The Endpoint Groups API allows you to manage groups of computers and servers.

Pre-requisites

You must have a set of API credentials (service principal) to be able to call the Endpoint API. For more information refer to the appropriate quick start guide:

Making API requests

You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the Endpoint API has the following general form:

curl -X<method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

  • <method>: The request method. For the Endpoint API, this is either GET or POST.
  • <tenant-id>: The ID of the tenant you want to query.
  • <jwt>: The JWT access token returned when the IDP authenticates the service principal.
  • <data-region>: The regional API host in the data geography where the tenant data is located.
  • <path>: The request path for the API operation, for example endpoint/v1/migrations.

The API descriptions in this guide only specify the request method and path. For example:

POST /endpoint/v1/endpoint-groups

To make an actual API request, you must expand this to the full form shown above.

All API requests return HTTP status codes 200 or 201 when successful. Javascript comments have been added to the JSON examples below for clarity.

List endpoint groups

API: GET /endpoint/v1/endpoint-groups

Response: Returns a paginated list of endpoint group objects.

{
  "items": [
      {
          "id": "a78239a7-d49d-41aa-836c-7fef82d5a946",    // Group ID
          "name": "HR desktops",                           // Group name
          "description": "Desktops of floor 12",           // Group description
          "type": "computer",                              // Group type. May also be "server"
          "endpoints": {                                   // Endpoints in this group
              "total": 5,                                  // Total number of endpoints in this group
              "itemsCount": 5,                             // Size of `items` array below
              "items": [                                   // A preview of the endpoints in this group
                  {
                      "id": "1b6bb9db-9c84-4643-ad8d-2fd37559b024",
                      "hostname": "DESKTOP-DF9FS4L"
                  },
                  {
                      "id": "9604e29e-db83-4e9c-8476-e07d44c9835a",
                      "hostname": "CLIENT1"
                  },
                  {
                      "id": "94010a29-7d3e-45de-b5cb-8f422c8e934b",
                      "hostname": "DESKTOP-75N0H61"
                  },
                  {
                      "id": "744712a6-f52d-4e17-b3a3-fa3e823c8bcf",
                      "hostname": "DESKTOP-E81QNNQ"
                  },
                  {
                      "id": "4bf28680-6f4e-4ce2-aa68-216d69acdb75",
                      "hostname": "JohnSmith-PC"
                  }
              ]
          },
          "tenant": {
              "id": "157922c3-c595-41d5-8454-5609b950f003"
          },
          "createdAt": "2019-03-10T14:07:11.659Z",
          "updatedAt": "2021-12-03T23:01:32.861Z"
      },
  ],
  "pages": {
    "current": 1,
    "size": 50,
    "maxSize": 1000
  }
}

Create new endpoint group

API: POST /endpoint/v1/endpoint-groups

Request body:

{
  "name": "Seattle computers",
  "description": "User devices in the Seattle office",
  "type": "computer",
  "endpointIds": [
    "e6a03d34-a943-45b7-8de3-deaf38864be4",
    "b7e5f3aa-a7c6-43c6-a65e-3cd52008464b",
    "f0316f62-6ce7-4008-99c5-6a1c209ab494"
  ]
}

Response: Returns the new endpoint group.

{
  "id": "439c06f2-f7f5-897e-065c-5618a4056ac7",
  "name": "Seattle computers",
  "type": "computer",
  "tenant": {
    "id": "157922c3-c595-41d5-8454-5609b950f003"
  },
  "description": "User devices in the Seattle office",
  "endpoints": {
    "total": 3,
    "itemsCount": 3,
    "items": [
      {
        "id": "e6a03d34-a943-45b7-8de3-deaf38864be4",
        "hostname": "Johns PC"
      },
      {
        "id": "b7e5f3aa-a7c6-43c6-a65e-3cd52008464b",
        "hostname": "Jane's MacBook"
      },
      {
        "id": "f0316f62-6ce7-4008-99c5-6a1c209ab494",
        "hostname": "comp-00349"
      }
    ]
  },
  "createdAt": "2022-06-24T15:45:49.892Z"
}

Get endpoint group by ID

API: GET /endpoint/v1/endpoint-groups/{groupId}

For example, GET /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7

Response: Returns the group object as in the previous section or 404 Not Found if the group was not found.

Update endpoint group

API: PATCH /endpoint/v1/endpoint-groups/{groupId}

For example, PATCH /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7

Request body:

{
  "name": "Seattle workstations",
  "description": "Workstations in the Seattle office"
}

Both fields in request body are optional.

Response: Returns the group with the updated name and description. You can't modify other group attributes using this API.

Get endpoints in group

API: GET /endpoint/v1/endpoint-groups/{groupId}/endpoints

For example, GET /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7/endpoints

Response: This returns the first page of the endpoints in the group. The response JSON has the same structure as that of the GET /endpoint/v1/endpoints API.

To fetch the next page, pass the query param pageFromKey set to the value of pages.nextKey in the response.

You can filter the view using the following (optional) query params:

  • sort: Sort by the given field name.
  • fields: Returns the requested fields instead of the whole endpoint object.
  • search: Returns endpoints that match the given search string.
  • searchFields: Comma-separated list of search fields for finding the given search term. This can contain one or more of: hostname, groupName, associatedPersonName, or ipAddresses. The default behavior is to match the search string against all these fields.

We have added a new parameter to the GET /endpoint/v1/endpoints API to perform the same operation in a different way.

API: GET /endpoint/v1/endpoints?groupId={groupId}

For example, GET /endpoint/v1/endpoints?groupId=439c06f2-f7f5-897e-065c-5618a4056ac7

To get endpoints that are not assigned to any group, call: GET /endpoint/v1/endpoints?assignedToGroup=false

Add endpoints to group

API: POST /endpoint/v1/endpoint-groups/{groupId}/endpoints

For example, POST /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7/endpoints

Request body: Pass the IDs of the endpoints to add. ids must contain at least one value. All endpoints must match the group type (computers or servers).

{
  "ids": [
    "8a4597a4-e5dd-4e0b-af6e-f627a4f1f699",  // Will be added
    "bf9907b2-df81-4531-9981-8c47cd24d5cc",  // Will be added
    "f0316f62-6ce7-4008-99c5-6a1c209ab494",  // Endpoint is already in the group
    "30359d2a-7009-42d5-abf3-e0d0bff037e9",  // Not an endpoint ID
    "fd4c976e-8bd1-4d16-9c7f-a7e50025163f"   // Endpoint type is `server`
  ]
}

Response: Adds any endpoints that aren't already in the group.

{
  "addedEndpoints": [
    "8a4597a4-e5dd-4e0b-af6e-f627a4f1f699",
    "bf9907b2-df81-4531-9981-8c47cd24d5cc"
  ],
  "errors": {
    "endpointsNotFound": [
      "30359d2a-7009-42d5-abf3-e0d0bff037e9"
    ],
    "endpointsOfWrongType": [
      "fd4c976e-8bd1-4d16-9c7f-a7e50025163f"
    ]
  }
}

The response doesn't contain the ID "f0316f62-6ce7-4008-99c5-6a1c209ab494" from the request as that endpoint is already in the group.

Remove endpoints from group

API: DELETE /endpoint/v1/endpoint-groups/{groupId}/endpoints?ids={id1},{id2},...

For example, to delete the two endpoints added in the previous section, call DELETE /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7/endpoints?ids=8a4597a4-e5dd-4e0b-af6e-f627a4f1f699,bf9907b2-df81-4531-9981-8c47cd24d5cc

Response: Removes any endpoints from the given list that are in the group. Endpoints not in the group are ignored.

{
  "removedEndpoints": [
    "8a4597a4-e5dd-4e0b-af6e-f627a4f1f699",
    "bf9907b2-df81-4531-9981-8c47cd24d5cc"
  ]
}

Remove a single endpoint from a group

API: DELETE /endpoint/v1/endpoint-groups/{groupId}/endpoints/{endpointId}

For example, DELETE /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7/endpoints/f0316f62-6ce7-4008-99c5-6a1c209ab494

Response: Returns whether the endpoint was removed from the group.

{
    "removed": true
}

Delete endpoint group

API: DELETE /endpoint/v1/endpoint-groups/{groupId}

For example, DELETE /endpoint/v1/endpoint-groups/439c06f2-f7f5-897e-065c-5618a4056ac7.

Response: Returns whether the group was deleted.

{
    "deleted": true
}

Conclusion

After reading this guide, you should be able to use the new API routes in the Endpoint API to manage endpoint groups.