API Changelog, Cisco Umbrella API

API Changelog

Learn about additions, updates, and deprecations to the Cisco Umbrella API.

May 21, 2025

Umbrella S3 Bucket Key Rotation API

• Added the S3 Bucket Key Rotation API.
  • POST /admin/v2/iam/rotateKey

March 31, 2025

Umbrella App Discovery API

• Added the App Discovery API endpoint:
  • GET /reports/v2/appDiscovery/applications/info

December 19, 2024

Umbrella Roaming Computers API

• Added the swgStatus query parameter for the Roaming Computers API endpoint:
  • GET /deployments/v2/roamingcomputers
• Added the swgStatus and lastSyncSwgStatus fields to the response for the Roaming Computers API endpoints:
  • GET /deployments/v2/roamingcomputers
  • GET /deployments/v2/roamingcomputers/{deviceId}
  • PUT /deployments/v2/roamingcomputers/{deviceId}

October 14, 2024

Integration Guides

• Moved the Cisco Cloud Security Umbrella Add-On for Splunk guide under legacy Umbrella APIs Integration Guides. For more information, see Cisco Cloud Security Umbrella Add-On for Splunk Integration Guide.
• Added the Cisco Cloud Security Add-On for Splunk (version 1.0.34) guide to the Cloud Security Integration Guides. For more information, see Cisco Cloud Security Add-On for Splunk. This guide describes how to integrate the Umbrella and Secure Access event data sources with Splunk in the add-on.

October 7, 2024

Umbrella Roaming Computers API

• Added the optional anyconnectDeviceId field to the response for these API endpoints:
  • GET /deployments/v2/roamingcomputers
  • GET /deployments/v2/roamingcomputers/{deviceId}
  • PUT /deployments/v2/roamingcomputers/{deviceId}

September 16, 2024

Umbrella Roaming Computers API

• Added the OrgInfo API endpoint.
  • GET /deployments/v2/roamingcomputers/orgInfo

July 17, 2024

Umbrella Secure Web Gateway Device Settings API

• Added the Umbrella Secure Web Gateway Device Settings API.
  • POST /deployments/v2/deviceSettings/SWGEnabled/set
  • POST /deployments/v2/deviceSettings/SWGEnabled/list
  • POST /deployments/v2/deviceSettings/SWGEnabled/remove

April 25, 2024

• Added the configuration of restricted networks on API keys in Umbrella. For more information, see Authentication.

January 31, 2024

Umbrella API Usage Reports API

• Added the Umbrella API Usage Reports API.
  • GET /reports/v2/apiUsage/requests
  • GET /reports/v2/apiUsage/responses
  • GET /reports/v2/apiUsage/keys
  • GET /reports/v2/apiUsage/summary

January 25, 2024

Umbrella Tagging API

• Added the Tagging API.
  • GET /deployments/v2/tags
  • POST /deployments/v2/tags
  • GET /deployments/v2/tags/{tagId}/devices
  • POST /deployments/v2/tags/{tagId}/devices
  • DELETE /deployments/v2/tags/{tagId}/devices

January 11, 2024

Umbrella Key Admin API

• Added the optional allowedIPs field on the following Key Admin API endpoints:
  • POST /admin/v2/apiKeys
  • GET /admin/v2/apiKeys/{apiKeyId}
  • PATCH /admin/v2/apiKeys/{apiKeyId}

Umbrella Destination Lists API

• Updated the bundleTypeId field to include the SAML Bypass type on the following Destination Lists API endpoints:
  • GET /policies/v2/destinationlists
  • POST /policies/v2/destinationlists

January 8, 2024

Umbrella Investigate API

• Added the Umbrella Investigate API to the Umbrella API (api.umbrella.com) under the investigate/v2 scope.

  • GET /investigate/v2/domains/categorization/{domain}
  • POST /investigate/v2/domains/categorization
  • GET /investigate/v2/domains/volume/{domain}
  • GET /investigate/v2/recommendations/name/{domain}.json
  • GET /investigate/v2/pdns/name/{domain}
  • GET /investigate/v2/pdns/domain/{domain}
  • GET /investigate/v2/pdns/ip/{ip}
  • GET /investigate/v2/pdns/raw/{anystring}
  • GET /investigate/v2/links/name/{domain}
  • GET /investigate/v2/security/name/{domain}
  • GET /investigate/v2/domains/risk-score/{domain}
  • GET /investigate/v2/bgp_routes/ip/{ip}/as_for_ip.json
  • GET /investigate/v2/bgp_routes/asn/{asn}/prefixes_for_asn.json
  • GET /investigate/v2/whois/{domain}
  • GET /investigate/v2/whois/{domain}/history
  • GET /investigate/v2/whois/nameservers/{nameserver}
  • GET /investigate/v2/whois/nameservers
  • GET /investigate/v2/whois/emails/{email}
  • GET /investigate/v2/whois/search/{searchField}/{regexExpression}
  • GET /investigate/v2/search/{expression}
  • GET /investigate/v2/topmillion
  • GET /investigate/v2/samples/{destination}
  • GET /investigate/v2/sample/{hash}
  • GET /investigate/v2/sample/{hash}/artifacts
  • GET /investigate/v2/sample/{hash}/connections
  • GET /investigate/v2/sample/{hash}/behaviors
  • GET /investigate/v2/timeline/{name}
  • GET /investigate/v2/subdomains/{domain}

• Moved the Umbrella Investigate API (investigate.api.umbrella.com) to the legacy Umbrella API.

November 27, 2023

Umbrella App Discovery API

• Added the application attributes App Discovery API endpoint.
  • GET /reports/v2/appDiscovery/applications/{applicationId}/attributes

October 5, 2023

Umbrella App Discovery API

• Added various field names to use with the sort query parameter.

  In addition to firstDetected, you can sort the collection on the lastDetected, name, and weightedRisk fields on the following endpoint:

  • /reports/v2/appDiscovery/applications

  In addition to firstDetected, you can sort the collection on the lastDetected field on the following endpoints:

  • /reports/v2/appDiscovery/protocols
  • /reports/v2/appDiscovery/applications/{applicationId}/identities
  • /reports/v2/appDiscovery/protocols/{protocolId}/identities

September 25, 2023

Umbrella Internal Domains API

• Added the siteIds field to the API request bodies. The siteIds field is optional.
  • POST /deployments/v2/internaldomains
  • PUT /deployments/v2/internaldomains/{internalDomainId}
• Added the siteIds field to the API responses of all operations except DELETE.
  • GET /deployments/v2/internaldomains
  • POST /deployments/v2/internaldomains
  • GET /deployments/v2/internaldomains/{internalDomainId}
  • PUT /deployments/v2/internaldomains/{internalDomainId}

September 13, 2023

Umbrella KeyAdmin API

• Added the description field to the API request bodies. The description field is optional.
  • POST /admin/v2/apiKeys
  • PATCH /admin/v2/apiKeys/{apiKeyId}
• Added the description field to the API responses of all operations except DELETE.
  • GET /admin/v2/apiKeys
  • POST /admin/v2/apiKeys
  • GET /admin/v2/apiKeys/{apiKeyId}
  • PATCH /admin/v2/apiKeys/{apiKeyId}
  • POST /admin/v2/apiKeys/{apiKeyId}/refresh

July 13, 2023

Umbrella API

• Added Umbrella Not for Resale (NFR) MSP DNS Advantage (312) package to the Umbrella Providers API endpoint:
  • POST /admin/v2/providers/customers

The Umbrella NFR MSP DNS Advantage package is only available in the Umbrella Secure MSP console.

April 18, 2023

Umbrella API

• Added Providers API endpoints
  • GET /admin/v2/providers/customerDeals/{dealId}
  • PUT /admin/v2/providers/customerDeals/{dealId}
  • GET /admin/v2/providers/customers/{customerId}/trialStrengths
  • GET /admin/v2/providers/customers/packages
  • GET /admin/v2/providers/customerAddresses
  • POST /admin/v2/providers/customers/{customerId}/accessRequest
  • GET /admin/v2/providers/customers/{customerId}/accessRequest/{accessRequestId}
  • PUT /admin/v2/providers/customers/{customerId}/accessRequest/{accessRequestId}
  • POST /admin/v2/providers/customers/{customerId}/trialExtensions
  • GET /admin/v2/providers/customers/{customerId}/subscriptionDetails
• Added Reporting API endpoints
  • GET /reports/v2/providers/customers/downloadReportRequests
  • POST /reports/v2/providers/customers/{customerId}/securityReportRequests
• Added Providers Console Configuration API endpoints
  • GET /admin/v2/config/cnames
  • POST /admin/v2/config/cnames
  • GET /admin/v2/config/cname/{cnameId}
  • PUT /admin/v2/config/cname/{cnameId}
  • DELETE /admin/v2/config/cname/{cnameId}
  • GET /admin/v2/config/contacts
  • POST /admin/v2/config/contacts
  • GET /admin/v2/config/contact/{contactId}
  • PUT /admin/v2/config/contact/{contactId}
  • DELETE /admin/v2/config/contact/{contactId}
  • GET /admin/v2/config/logos
  • POST /admin/v2/config/logos
  • GET /admin/v2/config/logos/{logoId}
  • PUT /admin/v2/config/logos/{logoId}
  • DELETE /admin/v2/config/logos/{logoId}
• Added Users and Roles API endpoints
  • GET /admin/v2/organizations
  • POST /admin/v2/passwordResets/{customerId}

March 15, 2023

Umbrella Investigate API

• Added Umbrella Investigate API endpoint:
  • GET /subdomains/{domain}

January 11, 2023

Umbrella KeyAdmin API

• Added KeyAdmin API to Umbrella API in the admin scope. The Umbrella KeyAdmin API is generally available (GA).
  • POST /admin/v2/apiKeys
  • GET /admin/v2/apiKeys
  • GET /admin/v2/apiKeys/{apiKeyId}
  • PATCH /admin/v2/apiKeys/{apiKeyId}
  • DELETE /admin/v2/apiKeys/{apiKeyId}
  • POST /admin/v2/apiKeys/{apiKeyId}/refresh

December 8, 2022

Umbrella App Discovery API

• Added Umbrella App Discovery API base URI, https://api.umbrella.com/reports.us/v2. If Umbrella stores your App Discovery logs in a Cisco Umbrella data center located in North America, but you connect to the API from a region outside of North America, use the https://api.umbrella.com/reports.us/v2 base URI.

November 7, 2022

Umbrella Network Tunnels API

• Added initialized field to tunnel state data object in Umbrella API endpoints.
  • GET /deployments/v2/tunnels
  • GET /deployments/v2/tunnels/{id}/state
  • GET /deployments/v2/tunnelsState
• Added initialized field to tunnel state data object in legacy Umbrella API endpoints.
  • GET /organizations/{organizationId}/tunnels
  • GET /organizations/{organizationId}/tunnels/{id}/state
  • GET /organizations/{organizationId}/tunnelsState

September 1, 2022

Umbrella Reporting v2 API

• Updated Reporting v2 API endpoints in Umbrella API:
  • GET /reports/v2/activity no longer includes IP Layer Enforcement data.
  • (Deprecated) GET /reports/v2/activity/ip no longer returns data.
• Updated Reporting v2 API endpoints in legacy Umbrella API:
  • GET /v2/organizations/{organizationId}/activity no longer includes IP Layer Enforcement data.
  • (Deprecated) GET /v2/organizations/{organizationId}/activity/ip no longer returns data.

August 29, 2022

• Cloud Security API is generally available (GA). For more information, see Umbrella API GA Announcement.

August 26, 2022

Umbrella Network Tunnels API

• Added Network Tunnel debugging endpoints to legacy Umbrella API:
  • GET /organizations/{organizationId}/tunnels/{id}/events
  • GET /organizations/{organizationId}/tunnels/{id}/globalEvents/sourceIp/{ip}
• Added Network Tunnel debugging endpoints to Umbrella API:
  • GET /tunnels/{id}/events
  • GET /tunnels/{id}/globalEvents/sourceIp/{ip}

July 25, 2022

Cloud Security API (LA)

Added Umbrella App Discovery API in the Umbrella API reports scope. The Umbrella App Discovery API endpoints include:

• GET /reports/v2/appDiscovery/applications
• PATCH /reports/v2/appDiscovery/applications
• GET /reports/v2/appDiscovery/applications/{applicationId}
• PATCH /reports/v2/appDiscovery/applications/{applicationId}
• GET /reports/v2/appDiscovery/applications/{applicationId}/risk
• GET /reports/v2/appDiscovery/applications/{applicationId}/identities
• GET /reports/v2/appDiscovery/protocols
• GET /reports/v2/appDiscovery/protocols/{protocolId}
• GET /reports/v2/appDiscovery/protocols/{protocolId}/identities
• GET /reports/v2/appDiscovery/applicationCategories

June 15, 2022

Cloud Security API (LA)

Umbrella API reaches Limited Availability (LA) and includes the following APIs:

• Umbrella Destination Lists API
• Umbrella Internal Domains API
• Umbrella Internal Networks API
• Umbrella Network Tunnels API
• Umbrella Networks API
• Umbrella Network Devices and Policies API
• Umbrella Roaming Computers API
• Umbrella Sites API
• Umbrella Token Authorization API
• Umbrella Service Providers and MSPs API
• Umbrella User Config API
• Umbrella Virtual Appliances API
• Umbrella Reporting API
• Umbrella Provider Consoles API

May 20, 2022

Cloud Security API (EFT)

• Updated the Umbrella Admin Audit log and report. The Admin Audit log and report now includes events generated by the Umbrella Destination Lists API requests that create, delete, or update destinations, using the following endpoints:

  • POST /policies/v2/destinationlists
  • POST /policies/v2/destinationlists/{destinationListId}/destinations
  • DELETE /policies/v2/destinationlists/{destinationListId}
  • PATCH /policies/v2/destinationlists/{destinationListId}
  • DELETE /policies/v2/destinationlists/{destinationListId}/destinations/remove

  The Umbrella Admin Audit log report displays:

  • The comment associated with the created destination. See the Action field in the Admin Audit log report.
  • The owner of the Umbrella API key ID that created the Umbrella Destination Lists API request. See the User field in the Admin Audit log report.

May 5, 2022

Umbrella Network Tunnels API

• Removed resourceAttributes field. Network Tunnel endpoints that include the resourceAttributes field in a request body or response:
  • GET /organizations/{organizationId}/tunnels
  • POST /organizations/{organizationId}/tunnels
  • GET /organizations/{organizationId}/tunnels/{id}
  • PUT /organizations/{organizationId}/tunnels/{id}
  • POST /organizations/{organizationId}/tunnels/{id}/keys

April 26, 2022

Cloud Security API (EFT)

• Added Umbrella Network Tunnels API.

April 14, 2022

Cloud Security API (EFT)

• Added Umbrella Reporting API to the Cloud Security API (EFT).

Umbrella Network Tunnels API

• Added siteOriginId field. Network Tunnel endpoints that include the siteOriginId field in a request body or response:
  • GET /organizations/{organizationId}/tunnels
  • POST /organizations/{organizationId}/tunnels
  • GET /organizations/{organizationId}/tunnels/{id}
  • PUT /organizations/{organizationId}/tunnels/{id}
  • POST /organizations/{organizationId}/tunnels/{id}/keys
• Added sort by siteOriginId in filters query parameter. Umbrella Network Tunnel API endpoints that include the filters query parameter:
  • GET /organizations/{organizationId}/tunnels

Umbrella Service Providers API

• Added fields to Service Providers Customer resource:
  • addonDlp
  • addonCdfwL7
  • addonRbi
• Umbrella Service Providers API endpoints that include the addonDlp, addonCdfwL7, and addonRbi fields in a request body or response:
  • POST /serviceproviders/{serviceProviderId}/customers
  • PUT /serviceproviders/{serviceProviderId}/customers/{customerId}
  • GET /serviceproviders/{serviceProviderId}/customers

March 10, 2022

The Cloud Security API Early Field Trial (EFT) release begins.

• Updated API key management, authentication, and authorization. Enabled multi-scoped API keys.
• Updated API base URI, version, and scope in API endpoint paths.
  • /admin/v2/roles
  • /admin/v2/users
  • /admin/v2/users/{userId}
  • /auth/v2/token
  • /deployments/v2/internaldomains
  • /deployments/v2/internaldomains/{internalDomainId}
  • /deployments/v2/internalnetworks
  • /deployments/v2/internalnetworks/{internalNetworkId}
  • /deployments/v2/internalnetworks/{internalNetworkId}/policies
  • /deployments/v2/networks
  • /deployments/v2/networks/{networkId}
  • /deployments/v2/networks/{networkId}/policies
  • /deployments/v2/policies
  • /deployments/v2/policies/{policyId}/identities/{originId}
  • /deployments/v2/roamingcomputers
  • /deployments/v2/roamingcomputers/{deviceId}
  • /deployments/v2/sites
  • /deployments/v2/sites/{siteId}
  • /deployments/v2/virtualappliances
  • /deployments/v2/virtualappliances/{virtualApplianceId}
  • /policies/v2/destinationlists
  • /policies/v2/destinationlists/{destinationListId}
  • /policies/v2/destinationlists/{destinationListId}/destinations
  • /policies/v2/destinationlists/{destinationListId}/destinations/remove

March 4, 2022

Umbrella Network Tunnels API

• Added tunnel information endpoint to update a specific tunnel.

  PUT /organizations/{organizationId}/tunnels/{id}

February 10, 2022

Umbrella Investigate API

• Document /search/{expression} endpoint.
• Document /whois/search/{searchField}/{regexExpression} endpoint.
• Provide full endpoint paths and update descriptions of rate limits.

January 10, 2022

Umbrella Investigate API

• Updated the rate limits for the /domains/categorization endpoint. Rate limit changes take effect in 90 days on April 10, 2022.

December 1, 2021

Umbrella Investigate API

• As of January 2022, the Security Information for a Domain (/security/name/{domain}) response object is changing.

  The following response fields no longer return a value:

  • dga_score
  • perplexity
  • entropy
  • securerank2
  • pagerank
  • asn_score
  • prefix_score
  • rip_score

October 22, 2021

Umbrella Investigate API

• Updated limit parameter for Passive DNS endpoints.
  • GET /pdns/name/{domain}
  • GET /pdns/domain/{domain}
  • GET /pdns/ip/{ip}
  • GET /pdns/raw/{anystring}

October 20, 2021

Umbrella Network Tunnels API

• Added tunnel state information for all tunnels in an organization.

  GET /organizations/{organizationId}/tunnelsState

• Added tunnel state information for a tunnel in an organization.

  GET /organizations/{organizationId}/tunnels/{id}/state

October 1, 2021

Umbrella Reporting v2 API

• Added Cisco Umbrella client authentication code samples. For more information, see Cisco Umbrella Client Samples.

August 18, 2021

Umbrella Reporting v2 API

• Added the httperrors query parameter. The httperrors query parameter filters the collection for proxy requests that resulted in a TLS or certificate error.

April 23, 2021

Umbrella Reporting v2 API

• Updated the Application object. Replace app-type-id, app-name, and app-type with the following properties: id, type, label, category.
• Added the filternoisydomains and datalosspreventionstate query parameters.

April 14, 2021

Cloudlock Enterprise API

• The Cloudlock Enterprise API discontinued support of transport layer security (TLS) versions 1.0 and 1.1 on May 31, 2021. The Cloudlock Enterprise API supports TLS version 1.2.

April 7, 2021

Umbrella and Cloudlock API Documentation

• Updated and published Cloud Security API documentation.

Umbrella Investigate API

• Deprecated /ips/{ip}/latest_domains endpoint. Use the Passive DNS endpoints:
  • GET /pdns/name/{domain}
  • GET /pdns/domain/{domain}
  • GET /pdns/ip/{ip}
  • GET /pdns/raw/{anystring}

May 5, 2020

Umbrella Investigate API

• Added Risk Score endpoint.

  GET /domains/risk-score/{domain}

  The Risk Score endpoint provides the overall risk score of a domain and is based on an analysis of the lexical characteristics of the domain name, and patterns found in queries and requests to the domain.