Getting Started with VMware Carbon Black APIs

The VMware Carbon Black security products all provide APIs to access the data and functionality in the products. This enables scenarios such as interactive access from scripts during an incident investigation and persistent integration to a SIEM or SOAR tool. The information in this section uses Carbon Black Cloud for the examples, but the principles apply to all products.

The Carbon Black Cloud is a cloud-native Endpoint, Workload, & Container Protection Platform comprising multiple products. There are APIs specific to each product, and Platform APIs which are part of all products. This list has quick links to the APIs for each product:

Introduction to Rest APIs

Learn how Carbon Black Cloud APIs increase customer value by allowing our customers to easily integrate into their environments.

 

cURL API Requests

Learn how you can use cURL to run your REST API calls and the cURL command syntax to construct the commands. 

Postman API Requests

Learn how to use Postman to easily call the Carbon Black Cloud APIs.

API Error Handling and Troubleshooting

Learn how to understand Carbon Black Cloud API errors and effectively troubleshoot your requests.

API Error Codes​

400 Bad Request

Generic error that tells us there was a problem with the message sent​

A 400 error occurs when someone has created a bad request. This can happen if required fields are missing, header values are not filled in properly, the wrong verb is used and another call uses that verb, the API version is not up to date, required query parameters are missing, or the user sends an empty request.​

The solution for correcting this error type is to compare the fields, header values, verb, API version, query parameters, and request requirements with those in the API documentation on the Developer Network.​

401 Unauthorized

Indicates authentication has failed​ meaning that the API does not recognize the user.

This could be due to a missing or invalid API key, an expired token or session, or an incorrect hostname.​

​Potential solutions for correcting this error type include:​

  • Verifying the correct key type​
  • Verifying the API key is set and correct if using Postman or the SDK​
  • Verifying the token is not expired if using OAuth​
  • Verifying the hostname by comparing it with the authentication page on the developer network or the CBC URL​
403 Forbidden

Indicates that authorization has failed, typically due to inadequate permissions. This differs from the previous authentication error, because in this case, the API recognizes the user, but knows they don’t have access.​

​Potential solutions for this error type include:​

  • Verifying the access level and key type by comparing with the API documentation on the Developer Network​
  • Verifying the hostname by comparing it with the authentication page on the Developer Network or comparing it with the CBC URL​
404 Not Found

The server cannot find the requested resource. This can be caused by an incorrect Org key, incorrect permissions, an invalid API route, or calling a route that requires an ID without an ID or with one that doesn’t exist.​

​Potential solutions for this error type include:​

  • Verifying the Org key in the URL matches the Org key in CBC​
  • Verifying the access level, key type, and API route are correct by comparing to the API documentation on the Developer Network​
  • Verifying the ID is present and valid for applicable routes​
405 Method not allowed

The server knows the request method, but the target resource doesn’t support the method. This is can be caused when the wrong verb is used and there is no other call that uses that verb, the API route is incorrect, or the hostname is incorrect.​

Potential solutions for this error type include:​

  • Verifying the correct verb and route by comparing with the API documentation on the Developer Network​
  • Verifying the correct hostname by comparing it with the Authentication page on the Developer Network or the CBC URL​
​410 Gone

The resource requested by the client has been permanently deleted. Users may see this error when trying to call a deactivated API.​

Potential solutions for this error type include:​

  • Verifying the latest version of the API is being used by comparing it with API documentation on the Developer Network​
  • Checking for recent deactivation notices on UEX or the Developer Network​
​415 Unsupported Media Type

The server refuses to accept the request because the payload format is unsupported. This can be due to a missing or incorrectly formatted request body, an incorrect content-type header, or sending a string in the request when JSON is required.​

​The solution for this error type is to verify the correct format, headers, and fields for request by comparing with API documentation on the Developer Network​

​500 Internal Server

Indicates a server-side error. In some of the API routes, they can also occur if the user sends the wrong file type, i.e., sending a text file when a JSON file is required​

Potential solutions for this error type include:​

  • Verifying the correct file type is used for applicable routes​
  • Checking if a maintenance window or incident is active​
  • Escalating the issue​
  • Trying again later​

Additional Resources

API Documentation

View the full API Documentation for Carbon Black Cloud on the Developer Network.

This blog post provides an example of CBC Container API.

About the Author and Contributors

Jasmine Clark, Developer Relation Evangelist

Jasmine Clark is a Developer Relations Evangelist at VMware Carbon Black Cloud focused on API adoption, internal enablement, and developer engagement. She has a background in Software Engineering and enjoys traveling and making music.

Change log

The following updates were made to this guide:

Date

Description of Changes

03/22/22

Initial draft 

Filter Tags

Carbon Black Cloud Document API and Integration Intermediate Integrate