Sensor Update Services v2 API Migration
The Sensor Update Service v2 API will be deactivated on September 5, 2024.
Overview
The new v3 Sensor Update Services API lets you batch sensor updates automatically across your organization and provides visibility into the update jobs progress. This API can also update large quantities of devices — up to 250k — without putting your network at risk.
This guide is to assist Carbon Black Cloud customers in migrating from the v2 Sensor Update Services API to the v3 Sensor Update Services API.
In this document, you will find
- A mapping of deprecated v2 API endpoints to new v3 API endpoints
- A mapping of deprecated v2 API schema to new v3 API schema
- New endpoints and fields specific to the v3 API
Guides and Resources
- v3 Sensor Update Services API Documentation
- Carbon Black Cloud User Guide - Inventory
- Carbon Black Cloud Console Release Notes
- After migrating, learn how to increase security by removing unused API keys
If you did not update prior to July 31st 2024
- Review the log files of integrations that had not been updated to identify failures.
- Update the integrations to use the v3 Sensor Update Services API per this guide.
- If the integration does not allow reprocessing of failed actions, or if the sensor updates are urgent, use the Carbon Black Cloud console to initiate sensor updates.
API Endpoints
v2 API Endpoint Equivalencies and new v3 API Endpoints
| Operation | Legacy v2 Endpoint | New v3 Endpoint |
|---|---|---|
| Create Sensor Update Job | POST /sus/v2/orgs/{org_key}/jobs?job_type={job_type} | POST /sensor_update_service/v3/orgs/{org_key}/jobs |
| Get Sensor Update Job | GET /sus/v2/orgs/{org_key}/jobs/{job_id} | GET /sensor_update_service/v3/orgs/{org_key}/jobs/{job_id} |
| Search Sensor Update Jobs | GET /sus/v2/orgs/{org_key}/jobs?job_type={job_type} | GET /sensor_update_service/v3/orgs/{org_key}/jobs/_search |
| Stop Sensor Update Job | POST /sus/v2/orgs/{org_key}/jobs/{job_id}/status | DELETE /sensor_update_service/v3/orgs/{org_key}/jobs/{job_id} |
| Search Sensors in Sensor Update Job | GET /sus/v2/orgs/{org_key}/jobs/{job_id}/sensors | POST /sensor_update_service/v3/orgs/{org_key}/jobs/{job_id}/sensors/_search |
| Update Sensor Job Name | New in v3 | POST /sensor_update_service/v3/orgs/{org_key}/jobs/{job_id} |
| Export Sensors in Sensor Update Job | New in v3 | POST /sensor_update_service/v3/orgs/{org_key}/jobs/{job_id}/sensors/_export |
Schema Changes
The following table contains the new fields available when migrating to the v3 Sensor Update Services API. The fields or sub-fields not captured here remain the same for their respective API endpoints.
New Fields
| Operation | New Fields |
|---|---|
| Job | name, client_ip, pending, processing, current_sensor_versions |
| Sensor | device_id, device_name, start_time, update_time |
Substituted Fields
| Object | v2 Field | v3 Field |
|---|---|---|
| Job | sensors |
Sensors are now returned in a separate API call using either Search Sensors in Sensor Update Job or Export Sensors in Sensor Update Job |
| Job | failed_sensors_per_reason |
failed_sensor_counts |
| Sensor | initial_version |
current_version |
| Sensor | sensor_state |
status |
| Sensor | updated_version |
update_version |
For the full v3 Schema Definition, see the v3 Sensor Update Services API Documentation
Deactivation Timeline
The v2 Sensor Update Services API will not be deactivated earlier than 12 months after deprecation. The earliest deactivation date is mid 2024.
Last modified on June 3, 2024