This API lets Carbon Black Cloud Workload users query appliance registration details and health status.
This also allows user to fine tune appliance configurations like heartbeat interval.
Access Level: Before you create your API Key, you need to create a “Custom” Access Level:
API Key: When you create your API Key, use the Access Level Type of “Custom”, then select the Access Level you created.
Environment: use the URL of your Carbon Black Cloud console (this is the Dashboard URL)
API Route: {cbc-hostname}/applianceservice/v1/orgs/{org_key}
Note: when you insert your org_key, you must also remove the { } brackets.
Register an appliance.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
appliances.registration |
CREATE |
Request
POST {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances
Request Body
{
"api_key": "<string>",
"api_id": "<string>",
"name": "<string>",
"version": "<string>",
"plugin_version": "<string>",
"ip_address": "<string>",
"appliance_group_uuid": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
api_key |
API Secret Key for appliance | String | N/A |
api_id |
API Key ID for appliance | String | N/A |
name |
Appliance name | String | N/A |
version |
Appliance version | String | N/A |
plugin_version |
vCenter plugin version | String | N/A |
ip_address |
IP address of the appliance | String | N/A |
appliance_group_uuid |
Unique group identifier generated during registration | String | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully registered appliance | application/json | View example response below |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances
Request Body
{
"api_key": "34PY53HZGWVHQKZP6R5TMHU9",
"api_id": "JWN58JV6IT",
"name": "POC-Appliance",
"version": "1.0.0",
"plugin_version": "1.0.0",
"ip_address": "10.0.9.1",
"appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}
Response
{
"appliance_uuid": "cae48003-6301-423a-9c57-1f0ce89bac0a",
"appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}
Update an appliance’s information.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
appliances.registration |
UPDATE |
Request
PUT {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}
Request Body
{
"version": "<string>",
"plugin_version": "<string>",
"appliance_group_uuid": "<string>",
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
version |
Appliance version | String | N/A |
plugin_version |
vCenter plugin version | String | N/A |
appliance_group_uuid |
Unique group identifier generated during registration | String | N/A |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated appliance information | N/A | N/A |
403 | Forbidden | N/A | N/A |
404 | Appliance not found with the specified appliance ID | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
PUT https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/1234
Request Body
{
"version": "1.0.0",
"plugin_version": "1.0.0",
"appliance_group_uuid": "ef9688ed-62c4-44a1-a388-e41fcf50748b"
}
Response
200 OK No Content
Obtain health details of the specified appliance.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
appliances.registration |
READ |
Request
GET {cbc-hostname}/applianceservice/v1/orgs/{org_key}/appliances/{appliance_id}/health
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successful retrieved appliance health details | application/json | View example response below |
403 | Forbidden | N/A | N/A |
404 | Appliance not found with the specified appliance ID | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
GET https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/appliances/1234/health
Response
{
"appliance_health": "CONNECTED",
"gateway": "CONNECTED",
"apw": "CONNECTED",
"vsw": "CONNECTED",
"acs": "CONNECTED",
"vc_connectivity": "CONNECTED",
"inventory": "CONNECTED",
"ip_address": "10.0.0.1"
}
Health statuses can be one of CONNECTED
, DISCONNECTED
, UNHEALTHY
.
Post Worker HeartBeat time interval.
RBAC Permissions Required
Permission (.notation name) | Operation(s) |
---|---|
appliances.registration |
CREATE |
Request
POST {cbc-hostname}/applianceservice/v1/orgs/{orgKey}/workers/config
Request Body
{
"appliance_uuid": "<string>",
"appliance_group_uuid": "<string>",
"heartbeat_interval": "<integer>",
"workerType": "<string>"
}
Body Schema
Field | Definition | Data Type | Values |
---|---|---|---|
appliance_uuid |
Unique appliance identifier generated during registration | String | N/A |
appliance_group_uuid |
Unique group identifier generated during registration | String | N/A |
heartbeat_interval |
Heartbeat interval runtime in milliseconds | Integer | N/A |
workerType |
Appliance worker type | String | VSPHERE , APPLIANCE , ACCESS_CONTROL |
Response
Code | Description | Content-Type | Content |
---|---|---|---|
200 | Successfully updated appliance heartbeat interval | N/A | N/A |
403 | Forbidden | N/A | N/A |
500 | Internal Server Error | N/A | N/A |
Example
Request
POST https://defense-eap01.conferdeploy.net/applianceservice/v1/orgs/ABCD1234/workers/config
Request Body
{
"appliance_uuid": "f07f9fda-b122-11ea-b3de-0242ac130004",
"appliance_group_uuid": "f07f9fda-b122-11ea-b3de-0242ac130005",
"heartbeat_interval": "30000",
"workerType": "APPLIANCE"
}
Response
200 OK No Content