The Umbrella Reporting APIv1 will be End of Life on March 31, 2022

All customers must update to the Reporting APIv2 by this date: March 31, 2022. The APIv1 will be disabled after the EOL date. Customers who do not update by the EOL date will find that the APIv1 is unresponsive, due to having been disabled. We encourage all customers to fully adopt the APIv2 in a timely manner to avoid any disruption to their use of Umbrella Reporting via the API.

Why are we making this change?

To stay ahead of the ever-changing landscape of threats and malicious events that customers face every day, the Umbrella team continuously improves the Umbrella service by relying on inputs from our customers, their security operations teams, and industry best practices.

Toward that end, we released our Umbrella Reporting APIv2 over a year ago with improvements over the Umbrella Reporting APIv1.

The Reporting APIv2 represents a complete rethink of searching and filtering capabilities. Queries are no longer limited to one-to-one matching. There are now over 30 endpoints with the Reporting APIv2, where the APIv1 offered 3. And the APIv2 empowers access to information faster and in new and innovative ways, ultimately shortening query cycles.

How do I adopt the Reporting APIv2?

First, check and see whether you are still using Reporting APIv1. In the Reporting API queries, you can identify the currently used version and implement the new reporting API calls following the code examples below.

Since the Reporting APIv2 expands significantly upon APIv1, the following example APIv2 endpoints are not indicated as exact 1-for-1 replacements of APIv1. Rather these are examples to help demonstrate how to identify usage of the APIv1.

Note how the URLs distinguish between v1 and v2.

To move from the Security Activity APIv1 endpoint, start by identifying the Security Activity categories that are significant to you using the following:

https://reports.api.umbrella.com/v2/organizations/{orgId}/categories

Then check the API calls here to update to APIv2:

https://reports.api.umbrella.com/v1/organizations/<organizationId>/security-activity

Where can I find more information?

References:

https://developer.cisco.com/docs/cloud-security/#!reporting-v2-overview

Getting started:

To get started, please see the following guide

https://developer.cisco.com/docs/cloud-security/#!reporting-v2-getting-started

V2 Endpoints:

For a list of V2 endpoints, refer to Reporting API V2 Endpoints:

https://developer.cisco.com/docs/cloud-security/#!reporting-v2-endpoints

Learning Labs:

https://developer.cisco.com/learning/modules/cisco-umbrella

Postman Examples:

https://github.com/CiscoDevNet/cloud-security/tree/master/Umbrella/PostmanExamples/ReportingAPI%20V2

For additional questions, please contact umbrella-support@cisco.com .