VM Workloads Search API

Overview

This API lets Carbon Black Cloud Workload users visualize a materialized view from inventory and lcm services.

Requirements

  • Carbon Black Cloud Workload - You must have purchased one of the Carbon Black Cloud Workload packages.
  • Minimum sensor versions: Version: 3.8 (Windows) & 2.13 (Linux). Check they’re the correct sensor version.
  • All API calls require an API key with appropriate permissions see Authentication

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}/lcm/view/v2/orgs/{org_key}/compute_resources

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • For vSpere Workloads: Workload Management > View Workloads without sensors > workloads.vcenter.vm, allow permission to READ
  • For Public Cloud Workloads: Public Cloud > View public cloud inventory > public.cloud.inventory, allow permission to READ

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}/lcm/view/v2/orgs/{org_key}/compute_resources

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:
  • For vSpere Workloads: _API.Workload.Management:workloads.Vcenter.Vm, allow permission to READ
  • For Public Cloud Workloads: _API.Public.Cloud:Public.cloud.inventory, allow permission to READ

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

Check Compute Resource Eligibility

Submit the compute resource’s metadata to confirm eligibility for Carbon Black Cloud sensor installation


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_eligibility


Request Body - application/json 

{
  "guest_info_disabled": <boolean>,
  "guest_id": "<string>",
  "guest_full_name": "<string>",
  "tools_version_status": "<string>",
  "cb_launcher_version": "<string>",
  "cb_os_id": "<string>",
  "cb_os_version": "<string>"
}

Body Schema

Field Definition Data Type Values
guest_info_disabled Whether the guest info is disabled Boolean
guest_id The id of the operating system String
guest_full_name The operating system name String
tools_version_status The guest tools version status String Supported: GUEST_TOOLS_CURRENT, GUEST_TOOLS_NOT_INSTALLED, GUEST_TOOLS_SUPPORTED_NEW, GUEST_TOOLS_SUPPORTED_OLD
cb_launcher_version The version of the cb launcher String
cb_os_id The Carbon Black operating system id String
cb_os_version The operating system version String

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below. See Eligibility and Eligibility Codes for supported values
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_eligibility
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "guest_info_disabled": false,
  "guest_id": "centos8_64Guest",
  "guest_full_name": "Centos 8",
  "tools_version_status": "GUEST_TOOLS_CURRENT",
  "cb_launcher_version": "1",
  "cb_os_id": "Centos8",
  "cb_os_version": "8"
}
Response Body 
{
    "eligibility": "ELIGIBLE",
    "eligibility_code": null
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_eligibility
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "guest_info_disabled": true,
  "guest_id": "centos8_32Guest",
  "guest_full_name": "Centos 8",
  "tools_version_status": "GUEST_TOOLS_TOO_OLD",
  "cb_launcher_version": "1",
  "cb_os_id": "Centos8",
  "cb_os_version": "8"
}
Response Body 
{
    "eligibility": "NOT_ELIGIBLE",
    "eligibility_code": [
        "ISOLATION_TOOLS_SET_INFO_DISABLED"
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Compute Resources

Search either AWS or WORKLOAD compute resources in your organization.

Search AWS Compute Resources

Search AWS compute resources in your organization.


API Permissions Required

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


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_search


Request Body - application/json 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "exclusions": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Body Schema

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. 
{
  "deployment_type": [
    "AWS"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "name": [
    "ResourceName"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
query Query in lucene syntax and/or including value searches. String N/A
rows Maximum number of rows to return Integer Max: 10k
start What row to begin returning results from Integer
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "name",
  "order": "asc"
}]
order supports asc or desc

Supported Fields: cloud_provider_resource_id, create_time, installation_status, name, platform, platform_details

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria": {
    "deployment_type": ["AWS"],
    "auto_scaling_group_name": ["AutoScalingGroup"],
    "availability_zone": ["us-west-1c"],
    "cloud_provider_account_id": ["1234567890"],
    "virtual_private_cloud_id": ["vpc-id"]
  },
  "sort": [
    {
      "field": "name",
      "order": "ASC"
    }
  ]
}
Response Body 
{
    "num_found": 1,
    "results": [
        {
            "auto_scaling_group_name": "AutoScalingGroup",
            "availability_zone": "us-west-1c",
            "cloud_provider_account_id": "1234567890",
            "cloud_provider_resource_id": "i-id",
            "cloud_provider_tags": [
                "Name##Demo",
            ],
            "create_time": "2022-06-02T05:23:27Z",
            "deployment_type": "AWS",
            "external_ip": "1.1.1.1",
            "id": "abcd123-aws-i-abcd12355dfg",
            "image_description": "Amazon Linux",
            "image_id": "ami-abcd1234",
            "image_name": "amzn2-ami-kernel-5.10-hvm-2.0.20220426.0-x86_64-gp2",
            "installation_status": "NOT_INSTALLED",
            "instance_state": "running",
            "instance_type": "t2.micro",
            "internal_ip": "1.1.1.1",
            "name": "Demo",
            "org_key": "ABCD1234",
            "platform": "Unix/Linux",
            "platform_details": "Linux/UNIX",
            "region": "us-west-1",
            "security_group_id": [
                "sg-abcd123"
            ],
            "subnet_id": "subnet-abcd1234",
            "virtual_private_cloud_id": "vpc-id"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Search Workload Compute Resources

Search Workload compute resources in your organization

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_search

Request Body 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": [ "<string>" ],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "exclusions": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": [ "<string>" ],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ]
}

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. REQUIRED 
{
  "deployment_type": [
    "WORKLOAD"
  ]
}
Supported fields:
appliance_uuid, cluster_name, datacenter_name, deployment_type,esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version

See Workload Compute Resource for values
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "name": [
    "ResourceName"
  ]
}
Supported fields: appliance_uuid, cluster_name, datacenter_name, deployment_type, esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version
query Query in lucene syntax and/or including value searches. String N/A
rows Maximum number of rows to return Integer Max: 10k
start First row to use for pagination Long Default: 0
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "created_at",
  "order": "asc"
}]
order supports asc or desc

Supported fields: created_at, name, host_name, eligibility, installation_status, os_description, vmwaretools_version

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria":{
     "deployment_type": ["WORKLOAD"],
     "installation_status":[
        "NOT_INSTALLED",
        "PENDING",
        "ERROR"
     ]
  },
  "sort":[
     {
        "field":"created_at",
        "order":"DESC"
     },
     {
        "field":"eligibility",
        "order":"ASC"
     }
  ]
}
Response Body 
{
    "num_found": 3,
    "results": [
        {
            "id": "14101309",
            "appliance_uuid": "e66fdd46-2268-4f34-8a3f-226fa6d3edd0",
            "cluster_name": "cwp-bucket-1-cluster",
            "datacenter_name": "cwp-bucket-1-datacenter",
            "esx_host_name": "10.234.56.789",
            "esx_host_uuid": "a2311b42-3e53-8f21-97d7-66680007185f",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.234.56.789",
            "vcenter_uuid": "9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3",
            "name": "cwp-bucket-1-appliance",
            "host_name": "photon-machine",
            "created_at": "2020-10-29T16:37:17.610Z",
            "ip_address": "10.234.56.789",
            "eligibility": "UNSUPPORTED",
            "eligibility_code": [
                "Unsupported OS"
            ],
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "500edcd7-e8ff-868a-6513-4e2fabcfcccd",
            "os_description": "VMware Photon OS (64-bit)",
            "os_type": "OTHER",
            "os_architecture": "32",
            "vmwaretools_version": "11296"
        },
        {
            "id": "13764913",
            "appliance_uuid": "46fa4b1c-474b-4b2e-b3d3-56871f410455",
            "cluster_name": "cwp-bucket-2-cluster",
            "datacenter_name": "cwp-bucket-2-datacenter",
            "esx_host_name": "10.173.95.98",
            "esx_host_uuid": "50f21342-52b7-0946-3422-cbbf72eb2a52",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.173.88.158",
            "vcenter_uuid": "59c3c754-66bf-406b-be3a-aefb5d6e4662",
            "name": "cwp-bucket-2-windows_2008",
            "host_name": "appd2k8r2",
            "created_at": "2020-10-23T09:43:50.357Z",
            "ip_address": "10.173.88.13",
            "eligibility": "ELIGIBLE",
            "eligibility_code": null,
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "5012aa35-16e8-7f75-6d10-73fa86e58300",
            "os_description": "Microsoft Windows Server 2008 R2 (64-bit)",
            "os_type": "WINDOWS",
            "os_architecture": "64",
            "vmwaretools_version": "11328"
        },
        {
            "id": "13764912",
            "appliance_uuid": "46fa4b1c-474b-4b2e-b3d3-56871f410455",
            "cluster_name": "cwp-bucket-2-cluster",
            "datacenter_name": "cwp-bucket-2-datacenter",
            "esx_host_name": "10.173.95.98",
            "esx_host_uuid": "50f21342-52b7-0946-3422-cbbf72eb2a52",
            "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
            "vcenter_host_url": "10.173.88.158",
            "vcenter_uuid": "59c3c754-66bf-406b-be3a-aefb5d6e4662",
            "name": "cwp-bucket-2-centos_72",
            "host_name": "prome-1s-dhcp38.eng.vmware.com",
            "created_at": "2020-10-23T09:43:50.357Z",
            "ip_address": "10.173.88.57",
            "eligibility": "ELIGIBLE",
            "eligibility_code": null,
            "installation_status": "NOT_INSTALLED",
            "installation_status_code": null,
            "uuid": "501251d6-6470-aab6-a5ff-97e822f1e9c3",
            "os_description": "CentOS 7 (64-bit)",
            "os_type": "CENTOS",
            "os_architecture": "64",
            "vmwaretools_version": "10309"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Download Compute Resources

Async search compute resources in your organization and download them as csv or json. The request initiates search, once the search is ready, you will get notification to download the requested search result from the Carbon Black Cloud UI.

Download AWS Compute Resources

Download AWS compute resources matching specific criteria.


API Permissions Required

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


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_search/download


Request Body - application/json 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "exclusions": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "format": "<string>"
}

Body Schema

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. REQUIRED 
{
  "deployment_type": [
    "AWS"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "auto_scaling_group_name": [
    "AutoScalingGroup"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
format Format of the search result. String JSON, CSV
default: CSV
query Query in lucene syntax and/or including value searches. String N/A
rows Maximum number of rows to return Integer Max: 10k
start What row to begin returning results from Integer
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "name",
  "order": "asc"
}]
order supports asc or desc

Supported Fields: cloud_provider_resource_id, create_time, installation_status, name, platform, platform_details

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_search/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria": {
    "deployment_type": ["AWS"],
    "auto_scaling_group_name": ["AutoScalingGroup"],
    "availability_zone": ["us-west-1c"],
    "cloud_provider_account_id": ["1234567890"],
    "virtual_private_cloud_id": ["vpc-id"]
  },
  "sort": [
    {
      "field": "name",
      "order": "ASC"
    }
  ],
  "format": "CSV"
}
Response Body 
{
  "jobId": 120066
}
To download or review the Carbon Black Cloud Postman collection, click here.

Download Workload Compute Resources

Download Workload compute resources matching specific criteria.

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_search/download

Request Body 

{
  "start": <integer>,
  "rows": <integer>,
  "query": "<string>",
  "criteria": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": ["<string>"],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "exclusions": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": ["<string>"],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "sort": [
    {
      "field": "<string>",
      "order": "<string>"
    }
  ],
  "format": "<string>"
}

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. 
{
  "deployment_type": [
    "WORKLOAD"
  ]
}
Supported fields:
appliance_uuid, cluster_name, datacenter_name, deployment_type, esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version

See Workload Compute Resource for values
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "name": [
    "ResourceName"
  ]
}
Supported fields: appliance_uuid, cluster_name, datacenter_name, deployment_type, esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version
format Format of the search result. String JSON, CSV
default: CSV
query Query in lucene syntax and/or including value searches. String N/A
rows Maximum number of rows to return Integer Max: 10k
start First row to use for pagination Long Default: 0
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "device_timestamp",
  "order": "asc"
}]
order supports asc or desc

Supported fields: created_at, name, host_name, eligibility, installation_status, os_description, vmwaretools_version

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_search/download
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "start": 0,
  "rows": 0,
  "criteria":{
     "deployment_type": ["WORKLOAD"],
     "installation_status":[
        "NOT_INSTALLED",
        "PENDING",
        "ERROR"
     ]
  },
  "sort":[
     {
        "field":"created_at",
        "order":"DESC"
     },
     {
        "field":"eligibility",
        "order":"ASC"
     }
  ],
  "format": "CSV"
}
Response Body 
{
  "jobId": 120066
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get AWS Compute Resource Summary

Get AWS compute resource summary on required fields.


API Permissions Required

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


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_summarize


Request Body - application/json 

{
  "query": "<string>",
  "criteria": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "exclusions": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "summary_fields": [ "<string>" ]
}

Body Schema

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. 
{
  "deployment_type": [
    "AWS"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
query Query in lucene syntax and/or including value searches. String N/A
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "name": [
    "ResourceName"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
summary_fields Fields for summarization Array Supported fields: availability_zone, region, subnet_id, virtual_private_cloud_id, security_group_id

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_summarize
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "deployment_type": ["AWS"],
    "auto_scaling_group_name": ["AutoScalingGroup"],
    "availability_zone": ["us-west-1c"],
    "cloud_provider_account_id": ["1234567890"],
    "virtual_private_cloud_id": ["vpc-id"]
  },
  "summary_fields": ["availability_zone", "region", "subnet_id", "virtual_private_cloud_id", "security_group_id"]
}
Response Body 
{
    "summaries": [
        {
            "count": 14,
            "field": "availability_zone"
        },
        {
            "count": 17,
            "field": "security_group_id"
        },
        {
            "count": 16,
            "field": "subnet_id"
        },
        {
            "count": 6,
            "field": "region"
        },
        {
            "count": 7,
            "field": "virtual_private_cloud_id"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Compute Resource by ID

Get the compute resource by ID from your organization.


  • AWS Permissions Required

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud public.cloud.inventory READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.inventory:READ N/A - included in permission name Prod UK and AWS GovCloud (US)
  • Workload Permissions Required

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Public.Cloud:Public.cloud.inventory:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request

GET {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/{id}?deployment_type={deployment_type}

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}
  • Compute Resource with deployment_type=AWS

Examples

Request 
GET https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/id1234?deployment_type=AWS
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "auto_scaling_group_name": "AutoScalingGroup",
    "availability_zone": "us-west-1c",
    "cloud_provider_account_id": "1234567890",
    "cloud_provider_resource_id": "i-id",
    "cloud_provider_tags": [
        "Name##Demo-ASG",
    ],
    "create_time": "2022-06-02T05:23:27Z",
    "deployment_type": "AWS",
    "external_ip": "1.1.1.1",
    "id": "id1234",
    "image_description": "Amazon Linux 2 Kernel 5.10 AMI 2.0.20220426.0 x86_64 ",
    "image_id": "ami-abcd123443",
    "image_name": "amzn2-ami-kernel-5.10-hvm-2.0.20220426.0-x86_64-gp2",
    "installation_status": "NOT_INSTALLED",
    "instance_state": "running",
    "instance_type": "t2.micro",
    "internal_ip": "1.1.1.1",
    "name": "Demo-ASG",
    "org_key": "ABCD1234",
    "platform": "Unix/Linux",
    "platform_details": "Linux/UNIX",
    "region": "us-west-1",
    "security_group_id": [
        "sg-idgroup"
    ],
    "subnet_id": "subnet-id",
    "virtual_private_cloud_id": "vpc-id"
}
To download or review the Carbon Black Cloud Postman collection, click here.
  • Compute Resource with deployment_type=WORKLOAD

Examples

Request 
GET https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/12345678?deployment_type=WORKLOAD
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "id": "12345678",
    "appliance_uuid": "e66fdd46-2268-4f34-8a3f-226fa6d3edd0",
    "cluster_name": "cwp-bucket-1-cluster",
    "datacenter_name": "cwp-bucket-1-datacenter",
    "esx_host_name": "10.234.56.789",
    "esx_host_uuid": "a2311b42-3e53-8f21-97d7-66680007185f",
    "vcenter_name": "VMware vCenter Server 6.7.0 build-14368073",
    "vcenter_host_url": "10.234.56.789",
    "vcenter_uuid": "9a8a0be5-ae1e-49ce-b2aa-34bc7dc445e3",
    "name": "cwp-bucket-1-appliance",
    "host_name": "photon-machine",
    "created_at": "2020-10-29T16:37:17.610Z",
    "ip_address": "10.234.56.789",
    "eligibility": "UNSUPPORTED",
    "eligibility_code": [
        "Unsupported OS"
    ],
    "installation_status": "NOT_INSTALLED",
    "installation_status_code": null,
    "uuid": "500edcd7-e8ff-868a-6513-4e2fabcfcccd",
    "os_description": "VMware Photon OS (64-bit)",
    "os_type": "OTHER",
    "os_architecture": "32",
    "vmwaretools_version": "11296"
}
To download or review the Carbon Black Cloud Postman collection, click here.

Facet Compute Resources

Search and facet compute resources in your organization.

AWS Facet Compute Resources


API Permissions Required

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


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_facet


Request Body - application/json 

{
  "query": "<string>",
  "criteria": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "exclusions": {
    "deployment_type": ["<string>"],
    "auto_scaling_group_name": ["<string>"],
    "availability_zone": ["<string>"],
    "cloud_provider_account_id": ["<string>"],
    "cloud_provider_resource_id": ["<string>"],
    "cloud_provider_tags": ["<string>"],
    "id": ["<string>"],
    "installation_status": ["<string>"],
    "name": ["<string>"],
    "platform": ["<string>"],
    "platform_details": ["<string>"],
    "region": ["<string>"],
    "subnet_id": ["<string>"],
    "virtual_private_cloud_id": ["<string>"],
  },
  "terms": {
    "rows": <integer>,
    "fields": [
      "<string>"
    ]
  }
}

Body Schema

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. 
{
  "deployment_type": [
    "AWS"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "deployment_type": [
    "WORKLOAD"
  ]
}
Supported fields: auto_scaling_group_name, availability_zone, cloud_provider_account_id, cloud_provider_resource_id, cloud_provider_tags, deployment_type, id, installation_status, name, platform, platform_details, region, subnet_id, virtual_private_cloud_id
query Query in lucene syntax and/or including value searches. String N/A
terms The compute resource fields to facet and how many of the top entries to return. Object 
{
  "fields": [
    "auto_scaling_group_name"
  ],
  "rows": 20
}
Default: 20

Supported Fields: auto_scaling_group_name, cloud_provider_tags, platform, platform_details, virtual_private_cloud_id

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "deployment_type": ["AWS"]
  },
  "terms": {
    "rows": 100,
    "fields": ["auto_scaling_group_name", "cloud_provider_tags", "platform", "platform_details", "virtual_private_cloud_id"]
  }
}
Response Body 
{
    "terms": [
        {
            "field": "cloud_provider_tags",
            "values": [
                {
                    "id": "Name##CB-Installed-Oregon",
                    "name": "Name##CB-Installed-Oregon",
                    "total": 6
                },
                ...
            ]
        },
        {
            "field": "auto_scaling_group_name",
            "values": [
                {
                    "id": "Virginia-ASG",
                    "name": "Virginia-ASG",
                    "total": 5
                },
                ...
            ]
        },
        {
            "field": "virtual_private_cloud_id",
            "values": [
                {
                    "id": "vpc-abcd123",
                    "name": "vpc-abcd123",
                    "total": 16
                },
                ...
            ]
        },
        {
            "field": "platform_details",
            "values": [
                {
                    "id": "Linux/UNIX",
                    "name": "Linux/UNIX",
                    "total": 33
                },
                ...
            ]
        },
        {
            "field": "platform",
            "values": [
                {
                    "id": "Unix/Linux",
                    "name": "Unix/Linux",
                    "total": 36
                },
                ...
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Workload Facet Compute Resources


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud workloads.vcenter.vm READ Majority of environments
VMware Cloud Services Platform _API.Workload.Management:workloads.Vcenter.Vm:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request

POST {cbc-hostname}/lcm/view/v2/orgs/{org_key}/compute_resources/_facet


Request Body - application/json 

{
  "query": "<string>",
  "criteria": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": [ "<string>" ],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "exclusions": {
    "appliance_uuid": [ "<string>" ],
    "cluster_name": [ "<string>" ],
    "datacenter_name": [ "<string>" ],
    "deployment_type": [ "<string>" ],
    "esx_host_name": [ "<string>" ],
    "esx_host_uuid": [ "<string>" ],
    "vcenter_name": [ "<string>" ],
    "vcenter_host_url": [ "<string>" ],
    "vcenter_uuid": [ "<string>" ],
    "name": [ "<string>" ],
    "host_name": [ "<string>" ],
    "ip_address": [ "<string>" ],
    "device_guid": [ "<string>" ],
    "registration_id": [ "<string>" ],
    "eligibility": [ "<string>" ],
    "eligibility_code": [ "<string>" ],
    "installation_status": [ "<string>" ],
    "installation_type": [ "<string>" ],
    "uuid": [ "<string>" ],
    "os_description": [ "<string>" ],
    "os_type": [ "<string>" ],
    "os_architecture": [ "<string>" ],
    "vmwaretools_version": [ "<string>" ]
  },
  "terms": {
    "rows": <integer>,
    "fields": [
      "<string>"
    ]
  }
}

Body Schema

Field Definition Data Type Values
criteria REQUIRED Criteria is an object that represents values that must be in the results. Object deployment_type is REQUIRED and only the first value is used. 
{
  "deployment_type": [
    "WORKLOAD"
  ]
}
Supported fields:
appliance_uuid, cluster_name, datacenter_name, deployment_type,esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version

See Workload Compute Resource for values
exclusions Exclusions is a map that represents values that must not be in the results. Object 
{
  "name": [
    "ResourceName"
  ]
}
Supported fields: appliance_uuid, cluster_name, datacenter_name, deployment_type, esx_host_name, esx_host_uuid, vcenter_name, vcenter_host_url, vcenter_uuid, name, host_name, ip_address, device_guid, registration_id, eligibility, eligibility_code, installation_status, installation_type, uuid, os_description, os_type, os_architecture, vmwaretools_version
query Query in lucene syntax and/or including value searches. String N/A
terms The compute resource fields to facet and how many of the top entries to return. Object 
{
  "fields": [
    "eligibility"
  ],
  "rows": 20
}
Default: 20

Supported Fields: eligibility, installation_status, vmwaretools_version, os_type

Response

Code Description Content-Type Content
200 Successful Search Request. application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A 
{
    "error_code": null,
    "follow_up_api": null,
    "message": "Bad Request",
    "success": false
}
401 Unauthorized N/A 
{
  "message": "User is not authenticated",
  "success": false
}
403 Forbidden N/A 
{
  "error_code": "FORBIDDEN",
  "message": "User is not authorized",
  "success": false
}
500 Internal Server Error N/A 
{
  "error_code": "error.internal_server_error",
  "message": "Unexpected error occurred."
}

Examples

Request 
POST https://defense.conferdeploy.net/lcm/view/v2/orgs/ABCD1234/compute_resources/_facet
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "criteria": {
    "deployment_type": ["WORKLOAD"]
  },
  "terms": {
    "rows": 100,
    "fields": ["eligibility", "installation_status", "vmwaretools_version", "os_type"]
  }
}
Response Body 
{
    "terms": [
        {
            "field": "os_type",
            "values": [
                {
                    "id": "UBUNTU",
                    "name": "UBUNTU",
                    "total": 30
                },
                ...
            ]
        },
        {
            "field": "vmwaretools_version",
            "values": [
                {
                    "id": "10336",
                    "name": "10336",
                    "total": 27
                },
                ...
            ]
        },
        {
            "field": "eligibility",
            "values": [
                {
                    "id": "NOT_ELIGIBLE",
                    "name": "NOT_ELIGIBLE",
                    "total": 41
                },
                ...
            ]
        },
        {
            "field": "installation_status",
            "values": [
                {
                    "id": "NOT_INSTALLED",
                    "name": "NOT_INSTALLED",
                    "total": 52
                },
                ...
            ]
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Workload Compute Eligibility

Field Definition Data Type Values
eligibility The status indicator indicating whether a compute resource is capable of installing a Carbon Black Cloud sensor String ELIGIBLE, NOT_ELIGIBLE, UNSUPPORTED

Workload Compute Eligibility Codes

Field Definition Data Type Values
eligibility_code Reason messages for why a compute resource is not eligible Array Supported: LAUNCHER_NOT_FOUND, OLD_VMTOOLS, ISOLATION_TOOLS_SET_INFO_DISABLED, OS_TYPE_UNSUPPORTED, VM_TOOLS_NOT_INSTALLED, VM_OFFLINE

Workload Compute Resource

Field Definition Data Type Values
id Numerical identifier for the compute resource String N/A
appliance_uuid The UUID of the appliance the VM is associated with. String N/A
cluster_name Name of the cluster. A cluster is a group of hosts. String N/A
datacenter_name Name of the underlying datacenter. The datacenter managed object provides the interface to the common container object for hosts, virtual machines, networks, and datastores. String N/A
deployment_type Deployment Type String WORKLOAD
esx_host_name Name of the ESX host on which the VM is deployed String N/A
esx_host_uuid UUID of the ESX host on which VM is deployed String N/A
vcenter_name Name of the vcenter the vm is associated with String N/A
vcenter_host_url The hostname or ip address of the vcenter the vm is associated with String N/A
vcenter_uuid 128-bit SMBIOS UUID of a vcenter represented as a hexadecimal string String N/A
name The name of the compute resource String N/A
host_name The DNS name of associated with the compute resource String N/A
created_at The timestamp the compute resource was created ISO 8601 UTC timestamp N/A
ip_address The current ip address assigned to the compute resource String N/A
eligibility The status indicator indicating whether a compute resource is capable of installing a Carbon Black Cloud sensor String ELIGIBLE, NOT_ELIGIBLE, UNSUPPORTED
eligibility_code Reason messages for why a compute resource is not eligible Array 
["<string>"]

VMware Tools install required,
VMware Tools update required,
Launcher not found,
VM is offline,
Unsupported OS
installation_status The current state of installing the Carbon Black Cloud sensor on the compute resource String SUCCESS, ERROR, PENDING, NOT_INSTALLED
installation_status_code The reason an the installation process is in an ERROR state String Unsuccessful install, OLD_VMTOOLS
uuid Universally unique identifier for a compute resource String N/A
os_description The operating system, version, and architecture String N/A
os_type The type of operating system String WINDOWS, RHEL, UBUNTU, SUSE, SLES, CENTOS, OTHER, AMAZON_LINUX, ORACLE
os_architecture The compute resource’s operating system architecture String 32, 64
vmwaretools_version The current version of VMware tools installed in the compute resource String N/A

AWS Compute Resource

Field Definition Data Type Values
auto_scaling_group_name Auto scaling group name String N/A
availability_zone AWS availability zone String N/A
cloud_provider_account_id Account id of the cloud provider String N/A
cloud_provider_resource_id Resource id assigned by cloud provider String N/A
cloud_provider_tags Cloud provider tags Array N/A
create_time Create Time String N/A
deployment_type Deployment type String AWS
external_ip The current external IP address assigned to the compute resource String N/A
id Identifier for the compute resource String N/A
image_description Image description String N/A
image_id Image id String N/A
image_name Image name String N/A
installation_status The current state of installing the Carbon Black Cloud sensor on the compute resource String SUCCESS, ERROR, PENDING, NOT_INSTALLED
installation_state The installation state in AWS String N/A
instance_type Instance type String N/A
internal_ip The current internal IP address assigned to the compute resource String N/A
name The name of the compute resource String N/A
org_key Organization key in Carbon Black Cloud String N/A
platform Platform String N/A
platform_details Platform details String N/A
region AWS region String N/A
security_group_id Security group id String N/A
subnet_id Subnet id String N/A
virtual_private_cloud_id Virtual private cloud id String N/A

Last modified on April 11, 2023