Asset Groups API


Overview

Asset Groups provides a way to organize and manage your fleet of Endpoints, VM Workloads, and VDIs. Create groups of assets and apply policies to the groups so the protections of all similar assets are synchronized. The ability to add one asset to multiple groups, and rank policies for precedence in application, gives added flexibility and fine tuning for complex organizations.

Key Features

  • Аssociate a policy with Group and automatically apply it to all the Group members' sensors
  • Define a group using search criteria to have assets dynamically included in the group when the criteria is met

Limits

There are certain limitations to be aware of when using Asset Groups. These limitations include:

  • Maximum of 100 groups per organization.
    • An organization can create and manage up to 100 different asset groups.
  • Maximum of 5 query criteria sets.
    • Example: You can define up to 10 sets of conditions to filter assets, such as “(a or b)”.
  • Maximum of 10 query attributes per criteria set.
    • Example: Within each criteria set, you can specify up to 10 query attributes to filter assets based on specific characteristics.
  • Maximum of 1 nesting level for queries.
    • Example: You can have a structure like “(a or b) and (c and d)”, where multiple conditions are combined using logical operators, but you cannot have further levels of nesting.

If you hit any of the aforementioned limitations while using the Asset Groups API, you will receive an HTTP 400 Bad Request response. The HTTP response will include a specific error code and description, providing details about the specific limitation that was exceeded.

Note: The maximum number of Asset Groups in one organization was increased to 100 on Jan 18th 2024

Use Cases

  • Apply policy settings across multiple assets at once.
  • Assign assets to groups manually from the Inventory pages.
  • Assign assets dynamically using group criteria.
  • Assign assets to multiple asset groups for better group configurability, while ranking your policies to ensure the correct policy is delivered to the correct asset.

Requirements

  • All Carbon Black Cloud APIs and Services require authentication, see Authentication for details.
  • Sensor Versions
    • Linux sensor versions 2.15+
    • Windows sensor versions 4.0+

Resources


Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups
  • {cbc-hostname}/asset_groups/v1/orgs/{org_key}/members

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • GM > Group Management > group-management, allow permission to CREATE, READ, UPDATE, DELETE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups
  • {cbc-hostname}/asset_groups/v1/orgs/{org_key}/members

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.GM:Msm.group-Set, allow permission to CREATE, READ, UPDATE, DELETE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


API Calls

Note: The Asset Groups feature has certain limitations. These include a maximum of 100 groups per organization, a maximum of 10 query criteria sets, a maximum of 10 query attributes per criteria set, and a maximum of one nesting level for queries. For more details, please refer to the Limits section.


Preview Policies Rank Change

Preview changes in the ranking of policies. Use this API call to see how a change in the rank of a policy or policies will affect assets.
Rank policies in order of importance. When an asset is assigned more than one policy, the highest-ranking policy takes precedence.

To view order of policies based on their ranking, use the Get Policies Order by Rank API call.

To make the actual change in the rank of a policy or policies, use the Update Policy Ranks API call.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/policy-assignment/v1/orgs/{org_key}/policies/preview


Request Body - application/json

{
  "policies": {
    "id": <integer>,
    "position": <integer>
  }
}


Body Schema

Field Definition Data Type Values
policies Object 
{
  "id": <integer>,
  "position": <integer>
}
id Unique identifier of a policy. It is used to specify which policy you want to preview or potentially change the ranking for. Integer
position The desired new position or rank for the policy specified by the “id” parameter. It determines where the policy should be placed in relation to other policies when the ranking change is applied. When an asset is assigned more than one policy, the highest-ranking policy takes precedence. Integer


Response Codes

Code Description Content-Type Content
200 OK application/json Example response below
400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error


Examples

Request 
POST https://defense.conferdeploy.net/policy-assignment/v1/orgs/ABCD1234/policies/preview
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "policies": [
    {
      "id": 20314731,
      "position": 3
    }
  ]
}
Response Body 
{
  "preview": [
    {
      "current_policy": {
        "id": 20578754,
        "position": 3
      },
      "new_policy": {
        "id": 20314731,
        "position": 3
      },
      "asset_count": 18,
      "asset_query": "(ag_agg_key_manual:970ca9a0cb0867e32379319c3245ea87f3057201d9e053c97e8ab76c06c14f4e AND ag_agg_key_dynamic:e72a656b6ba284e903239c5483cc0bf57ce02277d77d8f2356ecf14385388eb2 AND policy_id:20578754 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:e72a656b6ba284e903239c5483cc0bf57ce02277d77d8f2356ecf14385388eb2 AND policy_id:20578754 AND policy_override:false)",
      "assets_search_definition": {
        "query": "(ag_agg_key_manual:970ca9a0cb0867e32379319c3245ea87f3057201d9e053c97e8ab76c06c14f4e AND ag_agg_key_dynamic:e72a656b6ba284e903239c5483cc0bf57ce02277d77d8f2356ecf14385388eb2 AND policy_id:20578754 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:e72a656b6ba284e903239c5483cc0bf57ce02277d77d8f2356ecf14385388eb2 AND policy_id:20578754 AND policy_override:false)"
      }
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Groups

Use the endpoints in this section to create, update and delete groups, as well as search for existing groups.


Preview Asset Groups Change

Preview changes related to asset groups within an organization, such as adding or removing members, creating or updating asset groups, and managing policy overrides.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.policies READ Majority of environments


Request 
POST {cbc-hostname}/policy-assignment/v1/orgs/ABCD1234/asset-groups/preview


Request Body - application/json

{
  "action": "<string>",
  "asset_ids": [
    <integer>
  ],
  "asset_group_query": "<string>",
  "policy_id": <integer>,
  "asset_group_ids": [
    "<string>"
  ],
  "assets_search_definition": {
    "criteria": {
      "<key>": "<value>"
    },
    "start": <integer>,
    "rows": <integer>,
    "query": "<string>"
  }
}


Body Schema

Field Definition Data Type Values
action The action to be previewed String ADD_MEMBERS, REMOVE_MEMBERS, ADD_POLICY_OVERRIDE, REMOVE_POLICY_OVERRIDE, ASSET_GROUPS_CREATE, ASSET_GROUPS_UPDATE, ASSET_GROUPS_DELETE
policy_id The unique identifier of the policy associated with the asset groups. Integer N/A
asset_group_ids An array of unique identifiers (UUIDs) representing asset groups to be previewed. Array of Strings [“a1b2c3d4”, “e5f6g7h8”]
asset_ids An array of integers representing unique asset identifiers to be previewed. Array of Integers [123, 456, 789]
asset_group_query A string containing a query to filter asset groups based on certain criteria. String Example: “type=workstation”
assets_search_definition An object containing search definitions for assets. This includes criteria, start, rows, and query parameters. Object N/A
assets_search_definition.criteria An object defining criteria for searching assets. Object {}
assets_search_definition.start The starting index for paginating through assets. Integer 0
assets_search_definition.rows The number of rows per page for paginating through assets. Integer 10
assets_search_definition.query A string containing a query to filter assets based on certain criteria. String Example: “status=active”


Response Codes

Code Description Content-Type Content
200 OK application/json Example Response Below
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Examples

Request 
POST https://defense.conferdeploy.net/policy-assignment/v1/orgs/ABCD1234/asset-groups/preview
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "action": "ASSET_GROUPS_UPDATE",
  "policy_id": 465946,
  "asset_group_ids": [
    "6459233a-3b5c-4982-9f34-731542524e37"
  ]
}
Response Body 
{
    "preview": [
        {
            "current_policy": {
                "id": 20314731,
                "position": 4
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 24,
            "asset_query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND "
            }
        },
        {
            "current_policy": {
                "id": 19305221,
                "position": 14
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 17,
            "asset_query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)"
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/policy-assignment/v1/orgs/ABCD1234/asset-groups/preview \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
 --data-raw '{
  "action": "ASSET_GROUPS_UPDATE",
  "policy_id": 465946,
  "asset_group_ids": [
    "6459233a-3b5c-4982-9f34-731542524e37"
  ]
}'
Response Body 
{
    "preview": [
        {
            "current_policy": {
                "id": 20314731,
                "position": 4
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 24,
            "asset_query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND "
            }
        },
        {
            "current_policy": {
                "id": 19305221,
                "position": 14
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 17,
            "asset_query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)"
            }
        }
    ]
}
    "preview": [
        {
            "current_policy": {
                "id": 20314731,
                "position": 4
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 24,
            "asset_query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:84982a450d3db4f41c56ae897d8d8cf825377a1b56fab82ba76a1dcf7456d943 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:db51c36492ba4774816f80cfab2b3a5e50a0f82d4c0469f2477d3b70eb92a11f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:4e2ebb14e27c7973236d1a88c46d048c89a5dc45f1d230bc6bf65d1c0f6ebd3f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:678fad1d2b705c3d1926e7c5818ca0486aa57fea1e7a2f9656a3aaee02115e13 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:e380552e82fbd5b5808cb16127dfe80ad528f332de04f6b563706b2b1205659e AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:84982a450d3db4f41c56ae897d8d8cf825377a1b56fab82ba76a1dcf7456d943 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:f6da4be136f36c87c8948e76d3d1155d4132848f721e4a7c07c64e0070ace373 AND ag_agg_key_dynamic:db51c36492ba4774816f80cfab2b3a5e50a0f82d4c0469f2477d3b70eb92a11f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:2a6923397427fe4ffd030c6942814945668ca97588a40359ea085b7211dca08f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:4e2ebb14e27c7973236d1a88c46d048c89a5dc45f1d230bc6bf65d1c0f6ebd3f AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:678fad1d2b705c3d1926e7c5818ca0486aa57fea1e7a2f9656a3aaee02115e13 AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false) OR (ag_agg_key_manual:e380552e82fbd5b5808cb16127dfe80ad528f332de04f6b563706b2b1205659e AND ag_agg_key_dynamic:20ec063296de7746ecfe2cfe372eedc1e1553514d06a625369f39de7ee6f5e67 AND policy_id:20314731 AND policy_override:false)"
            }
        },
        {
            "current_policy": {
                "id": 7784574,
                "position": 5
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 9,
            "asset_query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:002a93942a1bb20b7b80a92fd1739a3f2953f71ea358f35bf19ac233984e392d AND policy_id:7784574 AND policy_override:false) OR (ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:c4e9bd76791f48731099dcb99e963aff38666f5533506689fd0f9d6b5d49ff19 AND policy_id:7784574 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:002a93942a1bb20b7b80a92fd1739a3f2953f71ea358f35bf19ac233984e392d AND policy_id:7784574 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:002a93942a1bb20b7b80a92fd1739a3f2953f71ea358f35bf19ac233984e392d AND policy_id:7784574 AND policy_override:false) OR (ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:c4e9bd76791f48731099dcb99e963aff38666f5533506689fd0f9d6b5d49ff19 AND policy_id:7784574 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:002a93942a1bb20b7b80a92fd1739a3f2953f71ea358f35bf19ac233984e392d AND policy_id:7784574 AND policy_override:false)"
            }
        },
        {
            "current_policy": {
                "id": 20578754,
                "position": 3
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 1,
            "asset_query": "(ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:87faf0f835b1b73bebcd347f1c43030f631582feb47612d52a05ad330d8e90dc AND policy_id:20578754 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:7acb5fb9e807ac1b73ce5ed114f98337ed80e3ff613756ac0cee60c139ce7151 AND ag_agg_key_dynamic:87faf0f835b1b73bebcd347f1c43030f631582feb47612d52a05ad330d8e90dc AND policy_id:20578754 AND policy_override:false)"
            }
        },
        {
            "current_policy": {
                "id": 19305221,
                "position": 14
            },
            "new_policy": {
                "id": 465946,
                "position": 1
            },
            "asset_count": 17,
            "asset_query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)",
            "assets_search_definition": {
                "query": "(ag_agg_key_manual:2c7190a37a11f4af3635e77f2d7ee9f61f659f7c49afbb663435f7846c6ec0c7 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:778ec890dc1c1af1d4bfbf75883a1484fd78f30ca947a8837d994bfcaa559667 AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false) OR (ag_agg_key_manual:7ec2c5cb39116bccb5934c908a8fdbaae8c9169c42f615b6473f610f3e28054c AND ag_agg_key_dynamic:3172c9358f785d34651fb5ef52f91621cf859cc4369442656e39326006ab7c10 AND policy_id:19305221 AND policy_override:false)"
            }
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Create Asset Group

Create a new asset group. Asset groups are used to categorize and manage assets (devices or endpoints) based on specific criteria, making it easier to apply policies and perform security operations. By using dynamic criteria in the “query” parameter, you can create asset groups that adapt and change dynamically as the conditions are met, ensuring that the group always contains relevant assets.

The system is asynchronous and eventually consistent. This may become more evident with groups that use dynamic criteria with large numbers of assets, and/or when there’s a large overlap in asset group membership between groups. When writing automated scripts, use the status field to determine when the asset group membership has finished updating;OK indicates the membership evaluation is complete, UPDATING indicates that group’s dynamic memberships are being re-evaluated as a result of change to group’s dynamic criteria.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management CREATE Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:CREATE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups

Request Body - application/json 

{
  "description": "<string>",
  "member_type": "<string>",
  "name": "<string>",
  "query": "<string>",
  "policy_id": <integer>
}

Body Schema

Field Required Definition Data Type Values
description Yes Group description String
member_type Yes Type of content this group has String DEVICE
name Yes Group Name String
query No Lucene query string used to search and add custom query String
policy_id No The policy that will be applied to assets in this group when this policy has the highest ranking Integer

Response

Code Description Content-Type Content
200 OK application/json View example response below.
Schema: Asset Group
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "description": "Test5",
  "member_type": "DEVICE",
  "name": "Test5",
  "query": "os_version:Windows",
  "policy_id": 7113785
}
Response Body 
{
  "id": "acb84a23-235b-4d0c-bdad-1390405c6dd5",
  "name": "Test5",
  "description": "Test5",
  "org_key": "ABCD1234",
  "status": "UPDATING",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:26:35.217Z",
  "update_time": "2023-03-23T13:26:35.217Z",
  "query": "os_version:Windows",
  "member_count": 0,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
  "description": "Test5",
  "member_type": "DEVICE",
  "name": "Test5",
  "query": "os_version:Windows",
  "policy_id": 7113785
}'
Response Body 
{
  "id": "acb84a23-235b-4d0c-bdad-1390405c6dd5",
  "name": "Test5",
  "description": "Test5",
  "org_key": "ABCD1234",
  "status": "UPDATING",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:26:35.217Z",
  "update_time": "2023-03-23T13:26:35.217Z",
  "query": "os_version:Windows",
  "member_count": 0,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Update Asset Group


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management UPDATE Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:UPDATE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
PUT {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}

Request Body - application/json 

{
  "description": "<string>",
  "member_type": "<string>",
  "name": "<string>",
  "query": "<string>",
  "policy_id": <integer>
}

Body Schema

Field Required Definition Data Type Values
description Yes Group description String
member_type Yes Type of content this group has String DEVICE
name Yes Group Name String
query No Lucene query string used to search and add custom query String
policy_id No The policy that will be applied to assets in this group when this policy has the highest ranking Integer

Response

Code Description Content-Type Content
200 OK application/json View example response below.
Schema: Asset Group
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
PUT https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "description": "Test5 updated",
  "member_type": "DEVICE",
  "name": "Test5 updated",
  "query": "os_version:Windows",
  "policy_id": 7113785
}
Response Body 
{
  "id": "acb84a23-235b-4d0c-bdad-1390405c6dd5",
  "name": "Test5 updated",
  "description": "Test5 updated",
  "org_key": "ABCD1234",
  "status": "UPDATING",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:26:35.217Z",
  "update_time": "2023-03-23T13:37:26.096Z",
  "query": "os_version:Windows",
  "member_count": 7,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430 \
-X PUT \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
-d '{
  "description": "Test5 updated",
  "member_type": "DEVICE",
  "name": "Test5 updated",
  "query": "os_version:Windows",
  "policy_id": 7113785
}'
Response Body 
{
  "id": "acb84a23-235b-4d0c-bdad-1390405c6dd5",
  "name": "Test5 updated",
  "description": "Test5 updated",
  "org_key": "ABCD1234",
  "status": "UPDATING",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:26:35.217Z",
  "update_time": "2023-03-23T13:37:26.096Z",
  "query": "os_version:Windows",
  "member_count": 7,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Delete Asset Group


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management DELETE Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:DELETE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
DELETE {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
DELETE https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/ec53c457-14cf-4886-9b24-f6ac74117b95
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "id": "ec53c457-14cf-4886-9b24-f6ac74117b95",
  "name": "Test",
  "description": "Test Update",
  "org_key": "ABCD1234",
  "status": "OK",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2022-09-09T14:15:06.215Z",
  "update_time": "2022-09-30T13:03:03.914Z",
  "member_count": 0,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/ec53c457-14cf-4886-9b24-f6ac74117b95 \
-X DELETE \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "id": "ec53c457-14cf-4886-9b24-f6ac74117b95",
  "name": "Test",
  "description": "Test Update",
  "org_key": "ABCD1234",
  "status": "OK",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2022-09-09T14:15:06.215Z",
  "update_time": "2022-09-30T13:03:03.914Z",
  "member_count": 0,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get All Asset Groups

Retrieve information about all Asset Groups.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups


Query Parameters

Parameter Required Values Default
member_type No DEVICE DEVICE
rows No Integer 20
sort_field No id, member_count, name, policy_id, policy_name id
sort_order No asc, desc asc
start No Integer 0

Response

Code Description Content-Type Content
200 OK application/json View example response below.
Schema: [ Asset Group ]
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups?sort_field=name&sort_order=desc&rows=1
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "num_found": 1,
  "results": [
    {
      "id": "9b8b8d84-4a44-4a94-81ec-1f8ef52d4430",
      "name": "Test Updated",
      "description": "Test Updated",
      "org_key": "ABCD1234",
      "status": "OK",
      "member_type": "DEVICE",
      "discovered": false,
      "create_time": "2022-09-05T13:12:31.848Z",
      "update_time": "2022-09-06T15:20:29.539Z",
      "member_count": 2,
      "policy_id": 7113785,
      "policy_name": "Monitored"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups?sort_field=name&sort_order=desc&rows=1 \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "num_found": 1,
  "results": [
    {
      "id": "9b8b8d84-4a44-4a94-81ec-1f8ef52d4430",
      "name": "Test Updated",
      "description": "Test Updated",
      "org_key": "ABCD1234",
      "status": "OK",
      "member_type": "DEVICE",
      "discovered": false,
      "create_time": "2022-09-05T13:12:31.848Z",
      "update_time": "2022-09-06T15:20:29.539Z",
      "member_count": 2,
      "policy_id": 7113785,
      "policy_name": "Monitored"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search for Asset Groups

Search for Asset Groups that match specified criteria.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/_search

Request Body - application/json 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "discovered": [<boolean>],
    "name": ["<string>"],
    "policy_id": [<integer>],
    "group_id": ["<string>"],
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Body Schema

Field Required Definition Data Type Values
criteria No Object that represents values that must be in the results Object Content below
query No Full-text search query string searches given text in Group name, Group description and policy id String
rows No Maximum number or results to return per page Integer
sort No Collection of sort parameters that specify a field and order to sort the results Array Content below
start No Zero-indexed start row Integer

criteria

Field Required Definition Data Type Values
discovered No Not in use
name No Group name to match Array
policy_id No Policy Ids to match Array
group_id No Group Ids to match Array

sort

Field Required Definition Data Type Values
field No Field to sort on String id, name, member_count, policy_id, policy_name
order No Field sort order String ASC, DESC

Response

Code Description Content-Type Content
200 OK application/json View example response below
Schema: [ Asset Group ]
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "policy_id": [
      7113785
    ]
  },
  "query": "test"
}
Response Body 
{
  "num_found": 1,
  "results": [
    {
      "id": "9b8b8d84-4a44-4a94-81ec-1f8ef52d4430",
      "name": "Group Test",
      "description": "Group Test",
      "org_key": "ABCD1234",
      "status": "OK",
      "member_type": "DEVICE",
      "discovered": false,
      "create_time": "2022-09-05T13:12:31.848Z",
      "update_time": "2022-09-05T13:12:31.848Z",
      "member_count": 0,
      "policy_id": 7113785,
      "policy_name": "Monitored"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/_search \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "policy_id": [
      7113785
    ]
  },
  "query": "test"
}'
Response Body 
{
  "num_found": 1,
  "results": [
    {
      "id": "9b8b8d84-4a44-4a94-81ec-1f8ef52d4430",
      "name": "Group Test",
      "description": "Group Test",
      "org_key": "ABCD1234",
      "status": "OK",
      "member_type": "DEVICE",
      "discovered": false,
      "create_time": "2022-09-05T13:12:31.848Z",
      "update_time": "2022-09-05T13:12:31.848Z",
      "member_count": 0,
      "policy_id": 7113785,
      "policy_name": "Monitored"
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Asset Groups

Export Asset Groups that match specified criteria.

To receive the actual JSON or CSV results, you need to use the Job Service API. First, use the Get Job Details to get the status of the async job, then Download Job Output call to download the actual content.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/_export

Request Body - application/json 

{
  "query": "<string>",
  "criteria": {
    "discovered": [<boolean>],
    "name": ["<string>"],
    "policy_id": [<integer>],
    "group_id": ["<string>"],
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "format": "<string>"
}

Body Schema

Field Required Definition Data Type Values
criteria No Object that represents values that must be in the results Object Content below
query No Full-text search query string searches given text in Group name, Group description and policy id String
rows No Maximum number or results to return per page Integer
sort No Collection of sort parameters that specify a field and order to sort the results Array Content below
start No Zero-indexed start row Integer
format No The format to export the asset groups String JSON, CSV

criteria

Field Required Definition Data Type Values
discovered No Not in use
name No Group name to match Array
policy_id No Policy Ids to match Array
group_id No Group Ids to match Array

sort

Field Required Definition Data Type Values
field No Field to sort on String id, name, member_count, policy_id, policy_name
order No Field sort order String ASC, DESC

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "policy_id": [
      7113785
    ]
  },
  "query": "test",
  "format": "CSV"
}
Response Body 
{
    "job_id": 6031024
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/_export \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
--data-raw '{
  "criteria": {
    "policy_id": [
      7113785
    ]
  },
  "query": "test",
  "format": "CSV"
}'
Response Body 
{
    "job_id": 6031024
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Asset Group by ID


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}

Response

Code Description Content-Type Content
200 OK application/json View example response below
Schema: Asset Group
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/8972d53a-7faf-481e-b8b6-acde06a8c91d
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "id": "8972d53a-7faf-481e-b8b6-acde06a8c91d",
  "name": "Test4",
  "description": "Test4",
  "org_key": "ABCD1234",
  "status": "OK",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:24:04.272Z",
  "update_time": "2023-03-23T13:24:04.739Z",
  "query": "os_version:Windows",
  "member_count": 8,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/8972d53a-7faf-481e-b8b6-acde06a8c91d \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "id": "8972d53a-7faf-481e-b8b6-acde06a8c91d",
  "name": "Test4",
  "description": "Test4",
  "org_key": "ABCD1234",
  "status": "OK",
  "member_type": "DEVICE",
  "discovered": false,
  "create_time": "2023-03-23T13:24:04.272Z",
  "update_time": "2023-03-23T13:24:04.739Z",
  "query": "os_version:Windows",
  "member_count": 8,
  "policy_id": 7113785,
  "policy_name": "Monitored"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Asset Group Stats

For a given group, return counts of how many of its members belong to other groups, and counts of how many members belong to groups without Policy association.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}/membership_summary

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/membership_summary
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
  "intersections": [
    {
      "count": 1,
      "ids": [
        "test_member"
      ],
      "group_id": "9b8b8d84-4a44-4a94-81ec-1f8ef52d4430",
      "group_name": "Test Updated",
      "group_description": "Test Updated",
      "policy_id": 7113785,
      "policy_name": "Monitored"
    }
  ],
  "unassigned_properties": [
    {
      "type": "POLICY",
      "count": 0,
      "ids": []
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/membership_summary \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "intersections": [],
  "unassigned_properties": [
    {
      "type": "POLICY",
      "count": 0,
      "ids": []
    }
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Group Query

Get Asset Group Configuration

Get a summary of the asset groups configuration, for limits and supported device attributes.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/configuration

Response Codes

Code Description Content-Type Content
200 OK application/json Example Response Below
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/configuration
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "asset_groups_configuration_limits": {
        "max_groups_per_org": 125,
        "max_nesting_levels": 1,
        "max_query_criteria_sets": 5,
        "max_query_attributes_per_criteria_set": 10
    },
    "supported_device_attributes": [
        "os",
        "os_version",
        "ad_org_unit",
        "ad_domain",
        "ad_distinguished_name",
        "name",
        "last_internal_ip_address",
        "sensor_version",
        "vm_name",
        "vcenter_uuid",
        "cluster_name",
        "esx_host_name",
        "datacenter_name",
        "email",
        "vcenter_host_url",
        "login_user_name",
        "golden_device",
        "vdi_provider",
        "cloud_provider_account_id",
        "cloud_provider_scale_group",
        "cloud_provider_tags",
        "cloud_provider_network",
        "infrastructure_provider",
        "passive_mode",
        "quarantined",
        "last_external_ip_address"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/configuration \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
    "asset_groups_configuration_limits": {
        "max_groups_per_org": 125,
        "max_nesting_levels": 1,
        "max_query_criteria_sets": 5,
        "max_query_attributes_per_criteria_set": 10
    },
    "supported_device_attributes": [
        "os",
        "os_version",
        "ad_org_unit",
        "ad_domain",
        "ad_distinguished_name",
        "name",
        "last_internal_ip_address",
        "sensor_version",
        "vm_name",
        "vcenter_uuid",
        "cluster_name",
        "esx_host_name",
        "datacenter_name",
        "email",
        "vcenter_host_url",
        "login_user_name",
        "golden_device",
        "vdi_provider",
        "cloud_provider_account_id",
        "cloud_provider_scale_group",
        "cloud_provider_tags",
        "cloud_provider_network",
        "infrastructure_provider",
        "passive_mode",
        "quarantined",
        "last_external_ip_address"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Supported Attribute Keywords

Retrieve list of keywords that can be used in query

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/attributes

Response Codes

Code Description Content-Type Content
200 OK application/json Example Response Below
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/attributes
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
[
    {
        "name": "sensor_version",
        "type": "string",
        "matchers": [
            "not_equals",
            "contains",
            "ends_with",
            "not_contains",
            "equals",
            "starts_with"
        ]
    },
    {
        "name": "vcenter_uuid",
        "type": "string",
        "matchers": [
            "not_equals",
            "ends_with",
            "equals",
            "starts_with"
        ]
    },
    ... <truncated> ...
]
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/attributes \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
[
    {
        "name": "sensor_version",
        "type": "string",
        "matchers": [
            "not_equals",
            "contains",
            "ends_with",
            "not_contains",
            "equals",
            "starts_with"
        ]
    },
    {
        "name": "vcenter_uuid",
        "type": "string",
        "matchers": [
            "not_equals",
            "ends_with",
            "equals",
            "starts_with"
        ]
    },
    ... <truncated> ...
]
To download or review the Carbon Black Cloud Postman collection, click here.

Validate Query

Validates group query based on the content type


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments


Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/query_validation


Request Body - application/json

{
  "query": "<string>",
  "content_type": "<string>"
}


Body Schema

Field Definition Data Type Values
content_type The member_type associated with the group query will be applied. String DEVICE
query The query that will associated members to the group String


Response Codes

Code Description Content-Type Content
200 OK application/json Example Response Below
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/query_validation
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "query": "name:test",
  "content_type": "DEVICE"
}
Response Body 
{
  "valid": true
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/query_validation \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \ 
 --data-raw '{
  "query": "invalid:test",
  "content_type": "DEVICE"
}'
Response Body 
{
    "valid": false,
    "errors": [
        {
            "error_code": "AGS_INVALID_QUERY_INTERNAL",
            "message": "Invalid attribute [invalid] found in query.",
            "args": [
                "Invalid attribute [invalid] found in query."
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Members

Use calls in this section to change the assets that are included in a group and get details of the assets contained in groups.


Add Members to Asset Group


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management CREATE Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:CREATE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}/members

Request Body - application/json 

{
  "action": "<string>",
  "external_member_ids": ["<string>"]
}

Body Schema

Field Required Definition Data Type Values
action Yes Specific action that the API should perform String CREATE
external_member_ids Yes List of unique identifiers for external members that are associated with the asset group Array N/A

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "action": "CREATE",
  "external_member_ids": [
    "11412673"
  ]
}
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.

Remove Members from Asset Group


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management DELETE Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:DELETE N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}/members

Request Body - application/json 

{
  "action": "<string>",
  "external_member_ids": ["<string>"]
}

Body Schema

Field Required Definition Data Type Values
action Yes Specific action that the API should perform String REMOVE
external_member_ids Yes List of unique identifiers for external members that are associated with the asset group Array N/A

Response

Code Description Content-Type Content
204 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "action": "REMOVE",
  "external_member_ids": [
    "11412673"
  ]
}
Response Body 
No Content
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.


Get Asset Group Members


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
GET {cbc-hostname}/asset_groups/v1/orgs/{org_key}/groups/{group_id}/members


Query Parameters

Parameter Required Values Default
rows No Integer 20
start No Integer 0

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
GET https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "num_found": 1,
    "member_ids": [
        "12345678"
    ],
    "members": [
        {
            "external_member_id": "12345678",
            "dynamic": true,
            "manual": false
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/groups/9b8b8d84-4a44-4a94-81ec-1f8ef52d4430/members \
-X GET \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456'
Response Body 
{
  "num_found": 1,
  "member_ids": [
    "123456"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Find Which Member Belongs to Which Group

Given a list of member IDs, return a map where key is the member ID, and value is a list of group IDs to which it belongs.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud group-management READ Majority of environments
VMware Cloud Services Platform _API.GM:Msm.group-Set:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/asset_groups/v1/orgs/{org_key}/members

Request Body - application/json 

{
  "external_member_ids": ["<string>"],
  "membership_type" ["<string>"]
}

Body Schema

Field Required Definition Data Type Values
external_member_ids Yes List of unique identifiers for external members that are associated with the asset group Array N/A
membership_type No Type of memberships to be retrieved for the assets provided. If not passed, will retrieve all type of memberships. Array MANUAL, DYNAMIC

Response

Code Description Content-Type Content
200 OK application/json View example response below
400 Invalid Request N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A
500 Internal Server Error 
{
  "error_code": "string",
  "message": "string"
}

Examples

Request 
POST https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/members
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "external_member_ids": [
    "11412673"
  ]
}
Response Body 
{
  "11412673": [
    "ec53c457-14cf-4886-9b24-f6ac74117b95"
  ]
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
curl https://defense.conferdeploy.net/asset_groups/v1/orgs/ABCD1234/members \
-X POST \
-H 'X-AUTH-TOKEN: ABCDEFGHIJKLMNO123456789/ABCD123456' \
-H 'Content-Type: application/json' \
Response Body
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Asset Group

Field Definition Data Type Values
create_time The time the Asset Group was created in ISO 8601 UTC timestamp format to milliseconds ISO 8601 UTC timestamp e.g “2023-09-09T19:49:13.988Z”
description Asset Group description String “Machines that were identified as Domain Controllers”
discovered Not in use
id Unique identifier of the Asset Group String e.g. “2ce14284-5288-4294-a5a2-047c238a5602”
member_count Number of assets in this group Integer e.g. 2
member_type Type of assets this group has String DEVICE
name Name of the Asset Group String e.g. “Domain Controllers”
status String OK - Evaluation is complete for dynamic membership of the group
UPDATING - The group’s dynamic memberships are being re-evaluated as a result of change to group’s dynamic criteria
update_time The time the Asset Group was modified in ISO 8601 UTC timestamp format to milliseconds ISO 8601 UTC timestamp e.g “2023-09-09T20:02:31.798Z”
org_key Unique identifier of the organization the Asset Group belongs to String e.g. “ABCD1234”
policy_id The unique id of the policy that will be applied to assets in this group when this policy has the highest ranking Integer e.g.123456789
policy_name The name of the policy that will be applied to assets in this group when this policy has the highest ranking String e.g. “Standard Policy”

Give Feedback

New survey coming soon!


Last modified on January 16, 2024