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


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