Cisco Umbrella App Discovery API
The App Discovery API provides an overall view of application and protocol activity in your environment
OpenAPI Specification
openapi: 3.0.1
info:
title: Cisco Umbrella App Discovery API
description: 'The App Discovery API provides an overall view of application and protocol activity in your environment
and the potential risk indicated by this network traffic.'
version: 2.0.2
contact:
name: Cloud Security Developer Community
x-provenance:
method: harvested
authored_by: Cisco Umbrella
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
- type: source
url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
variables:
basePath:
default: reports/v2
tags:
- name: Applications
- name: Application Categories
- name: Protocols
- name: Identities
- name: Umbrella
paths:
/appDiscovery/applications:
get:
tags:
- Applications
- Umbrella
summary: List Applications
description: List all discovered applications.
operationId: getApplicationsAppDiscovery
parameters:
- $ref: '#/components/parameters/sources'
- $ref: '#/components/parameters/identity'
- $ref: '#/components/parameters/labels'
- $ref: '#/components/parameters/controllable'
- $ref: '#/components/parameters/weightedRisk'
- $ref: '#/components/parameters/categories'
- $ref: '#/components/parameters/subcategory'
- $ref: '#/components/parameters/subcategory_content_types'
- $ref: '#/components/parameters/appTypes'
- $ref: '#/components/parameters/date'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/applicationsSort'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/label_timestamp'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationList'
example:
items:
- id: 1234ay7
name: Umbrella
label: approved
weightedRisk: low
category: Security
subcategory: Content Management
subcategory_content_types:
- Conversational Chat
- Other
appType: saas
sources:
- name: cdfw
events: 50
blockedEvents: 25
- name: dns
events: 35
blockedRequests: 14
- name: swg
totalTraffic: 150
bytesIn: 50
bytesOut: 100
blockedBytesOut: 15
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
currentPage: 1
totalPages: 126
itemsCount: 251
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
patch:
tags:
- Applications
- Umbrella
summary: Update Applications
description: Update the labels for the applications.
operationId: patchApplications
requestBody:
$ref: '#/components/requestBodies/BulkApplicationBody'
security:
- oauthFlow:
- reports.appDiscovery:write
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkLabelApplications'
example:
timestamp: '2022-01-01T00:00:00.000Z'
number_of_apps: 45
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applications/{applicationId}:
get:
tags:
- Applications
- Umbrella
summary: Get Application
description: Get an application by ID.
operationId: getApplication
parameters:
- $ref: '#/components/parameters/applicationId'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationObject'
example:
id: eaqYExba
name: Umbrella
description: Offers threat intelligence solutions.
label: approved
weightedRisk: low
category: Security
appType: saas
url: https://umbrella.cisco.com/products/umbrella-investigate
vendor: Cisco
identitiesCount: 5
sources:
- name: cdfw
events: 50
blockedEvents: 25
- name: dns
events: 35
blockedRequests: 14
- name: swg
totalTraffic: 150
bytesIn: 50
bytesOut: 100
blockedBytesOut: 15
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
patch:
tags:
- Applications
- Umbrella
summary: Update Application
description: Update the label for the application. Provide an application label in the request body.
operationId: updateApplication
parameters:
- $ref: '#/components/parameters/applicationId'
requestBody:
content:
application/json:
schema:
type: object
required:
- label
properties:
label:
$ref: '#/components/schemas/Label'
example:
label: approved
security:
- oauthFlow:
- reports.appDiscovery:write
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationObject'
example:
id: eaqYExba
name: Umbrella
description: Offers threat intelligence solutions.
label: approved
weightedRisk: low
category: Security
appType: saas
url: https://umbrella.cisco.com/products/umbrella-investigate
vendor: Cisco
identitiesCount: 5
sources:
- name: cdfw
events: 50
blockedEvents: 25
- name: dns
events: 35
blockedRequests: 14
- name: swg
totalTraffic: 150
bytesIn: 50
bytesOut: 100
blockedBytesOut: 15
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applications/{applicationId}/risk:
get:
tags:
- Applications
- Umbrella
summary: Get Application Risk
description: Get the risk for the application.
operationId: getApplicationRisk
parameters:
- $ref: '#/components/parameters/applicationId'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationRisk'
example:
id: eaqYExba
name: Umbrella
weightedRisk: veryLow
businessRisk: low
usageType: indirect
webReputation: 50
financialViability: medium
dataStorage: structured
vendorCompliance:
- name: PCI_DSS
description: 'The Payment Card Industry Data Security Standard (PCI DSS)
is a widely accepted set of policies and procedures intended
to optimize the security of credit, debit, and cash card transactions
and protect cardholders against misuse of their personal information.'
status: true
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applications/{applicationId}/identities:
get:
tags:
- Applications
- Umbrella
summary: List Application Identities
description: List all identities for the application.
operationId: getApplicationIdentities
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/date'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/identitiesSort'
- $ref: '#/components/parameters/order'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationIdentityList'
example:
items:
- id: 10000
name: My Identity
sources:
- name: dns
requests: 100
blockedRequests: 100
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applications/{applicationId}/attributes:
get:
tags:
- Applications
- Umbrella
summary: List Application Attributes
description: List all attributes for the application.
operationId: getApplicationAttributes
parameters:
- $ref: '#/components/parameters/applicationId'
- $ref: '#/components/parameters/attributeCategories'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationAttributeCategoryList'
example:
attributesCategories:
- id: '2'
name: Data Security
attributes:
- id: '17'
name: SSL Cert Key Size
description: The SSL certificate key size refers to the length of the cryptographic key
values:
- name: size
value: '2048'
createdOn: '2023-07-06T09:23:53.552924+00:00'
updatedOn: '2023-08-21T16:49:19.151159+00:00'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/protocols:
get:
tags:
- Protocols
- Umbrella
summary: List Protocols
description: List all protocols.
operationId: getProtocols
parameters:
- $ref: '#/components/parameters/identity'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/protocolsSort'
- $ref: '#/components/parameters/order'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ProtocolList'
example:
items:
- id: 0j1b5Eh
name: ftp
description: File Transfer Protocol
events: 100
blockedEvents: 50
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/protocols/{protocolId}:
get:
tags:
- Protocols
- Umbrella
summary: Get Protocol
description: Get protocol by ID.
operationId: getProtocol
parameters:
- $ref: '#/components/parameters/protocolId'
- $ref: '#/components/parameters/date'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProtocolObject'
example:
id: 0j1b5EmA
name: ftp
description: File Transfer Protocol
identitiesCount: 5
events: 100
blockedEvents: 50
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/protocols/{protocolId}/identities:
get:
tags:
- Identities
- Umbrella
summary: List Protocol Identities
description: List identities for a specific protocol.
operationId: getProtocolIdentities
parameters:
- $ref: '#/components/parameters/protocolId'
- $ref: '#/components/parameters/date'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/identitiesSort'
- $ref: '#/components/parameters/order'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ProtocolIdentityList'
example:
items:
- id: 10000
name: My Identity
events: 100
blockedEvents: 50
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applicationCategories:
get:
tags:
- Application Categories
- Umbrella
summary: List Application Categories
description: List all application categories.
operationId: getApplicationCategories
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
security:
- oauthFlow:
- reports.appDiscovery:read
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationCategoryList'
example:
items:
- name: Security
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
/appDiscovery/applications/info:
get:
tags:
- Applications
- Umbrella
description: List the information about the applications.
operationId: getApplicationsInfo
summary: List Information for Applications
parameters:
- $ref: '#/components/parameters/sources'
- $ref: '#/components/parameters/identity'
- $ref: '#/components/parameters/labels'
- $ref: '#/components/parameters/controllable'
- $ref: '#/components/parameters/weightedRisk'
- $ref: '#/components/parameters/categories'
- $ref: '#/components/parameters/subcategory'
- $ref: '#/components/parameters/subcategory_content_types'
- $ref: '#/components/parameters/appTypes'
- $ref: '#/components/parameters/date'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/applicationsInfoSort'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/label_timestamp'
- $ref: '#/components/parameters/app_ids'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationListWithInfo'
example:
items:
- id: 0JdbV4dy
name: Twitter
label: unreviewed
weightedRisk: low
category: Social Networking
subcategory: Social Networking
subcategory_content_types:
- Conversational Chat
- Other
appType: saas
sources:
- name: cdfw
events: 0
blockedEvents: 0
- name: swg
totalTraffic: 0
bytesIn: 0
bytesOut: 0
blockedBytesOut: 0
- name: dns
requests: 3
blockedRequests: 0
firstDetected: '2022-01-01T00:00:00.000Z'
lastDetected: '2022-01-01T00:00:00.000Z'
description: 'Online social networking service that enables users to send
and read short messages called tweets.'
url: https://twitter.com
vendor: Twitter
identitiesCount: 1
currentPage: 1
totalPages: 126
itemsCount: 251
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
components:
headers:
Link:
schema:
type: string
description: 'Links to related resources, in the format defined by
[RFC 5988](https://tools.ietf.org/html/rfc5988#section-5).
If there is a next page, this header includes a link with relation type
`next` to the next page.'
securitySchemes:
oauthFlow:
type: oauth2
description: client credential flow
flows:
clientCredentials:
tokenUrl: https://api.umbrella.com/auth/v2/token
scopes:
reports.appDiscovery:write: Write reports app discovery
reports.appDiscovery:read: Read reports app discovery
parameters:
applicationId:
in: path
name: applicationId
description: The ID of the application.
required: true
schema:
type: string
protocolId:
in: path
name: protocolId
description: The ID of the protocol.
required: true
schema:
type: string
limit:
in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
description: The maximum number of items to return in the collection.
offset:
in: query
name: offset
schema:
type: integer
description: The number of items to skip before starting to collect the result set.
applicationsSort:
in: query
name: sort
schema:
type: string
enum:
- firstDetected
- lastDetected
- weightedRisk
- name
description: Specify the name of a field to sort the applications.
example: firstDetected
labelTimestamp:
in: query
name: labelTimestamp
schema:
type: string
format: date-time
description: The date and time (ISO 8601 timestamp) when the system updated the label.
example: '2025-01-01T00:00:00.000Z'
applicationsInfoSort:
in: query
name: sort
schema:
type: string
enum:
- firstDetected
- lastDetected
- weightedRisk
- name
- vendor
- identities
- dnsRequests
- firewallEvents
- blockedDnsRequests
- traffic
- inboundWebTraffic
- ruleStatus
- scannable
- totalEvents
- labels
- subcategory
description: Specify the name of a field to sort the information for the applications.
protocolsSort:
in: query
name: sort
schema:
type: string
enum:
- firstDetected
- lastDetected
description: Specify the name of a field to sort the application protocols.
example: firstDetected
identitiesSort:
in: query
name: sort
schema:
type: string
enum:
- firstDetected
- lastDetected
description: Specify the name of a field to sort the application identities.
example: lastDetected
order:
in: query
name: order
schema:
type: string
enum:
- asc
- desc
description: 'Specify the order to sort the collection. Valid values are: `asc` (ascending)
or `desc` (descending).'
example: asc
label_timestamp:
in: query
name: label_timestamp
schema:
type: string
format: date-time
example: '2022-01-01T00:00:00.000Z'
description: Filter the result set on the date and time (ISO 8601 timestamp) when the system updated the label.
sources:
in: query
name: sources
schema:
type: array
items:
type: string
enum:
- dns
- swg
- cdfw
style: form
explode: false
description: 'Specify the types of log source to filter the collection.
Valid values are: `dns`, `swg`, `cdfw`.'
example:
- cdfw
labels:
in: query
name: labels
schema:
type: array
items:
$ref: '#/components/schemas/Label'
style: form
explode: false
description: 'Specify the types of application classification to filter the collection.
Valid values are: `unreviewed`, `approved`, `notApproved`, `underAudit`.'
example:
- approved
weightedRisk:
in: query
name: weightedRisk
schema:
type: array
items:
$ref: '#/components/schemas/WeightedRisk'
style: form
explode: false
description: 'Specify the list of application weighted risk to filter the collection.
Valid values are: `veryLow`, `low`, `medium`, `high`, `veryHigh`.'
example:
- low
categories:
in: query
name: categories
schema:
type: array
items:
type: string
style: form
explode: false
description: Specify the list of application category to filter the collection.
example:
- Security
subcategory:
in: query
name: subcategory
schema:
type: array
items:
type: string
style: form
explode: false
description: Specify the list of application subcategory to filter the collection.
example:
- Security
subcategory_content_types:
in: query
name: subcategory_content_types
schema:
type: array
items:
type: string
style: form
explode: false
description: Specify the list of content types for the application subcategory to filter the collection.
example:
- Conversational Chat
app_ids:
in: query
name: app_ids
schema:
type: array
items:
type: string
style: form
explode: false
description: The IDs of the applications to use when filtering the collection.
example:
- '1356'
attributeCategories:
in: query
name: categories
schema:
type: array
items:
type: string
style: form
explode: false
description: The categories of the attributes to use when filtering the collection.
example:
- Compliance
controllable:
in: query
name: controllable
schema:
type: string
enum:
- all
- advanced
description: 'Specify the type of controllable applications to filter the collection.
Valid values are: `all`, `advanced`.'
example: advanced
identity:
in: query
name: identity
schema:
type: integer
description: Specify the entity ID to filter the collection.
example: 12355
appTypes:
in: query
name: appTypes
schema:
type: array
items:
$ref: '#/components/schemas/AppType'
example:
- saas
- paas
- iaas
style: form
explode: false
description: 'Specify the types of application to filter the collection.
Valid values are: `saas`, `paas`, and `iaas`.'
example:
- paas
date:
in: query
name: date
schema:
type: string
format: date
description: 'Specify a date to search for data within a twenty-four hour time period.
If you do not provide a date, the last 90 days period is used to query the collection.'
example: '2022-01-01'
responses:
InvalidRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBodies:
BulkApplicationBody:
description: A JSON object containing application information for bulk label update.
required: true
content:
application/json:
schema:
type: object
properties:
label:
$ref: '#/components/schemas/Label'
applicationsList:
type: array
description: Provide a list of application ID to update.
items:
type: string
minItems: 1
maxItems: 1000
example:
- abd1
example:
label: approved
applicationsList:
- 1a
- 2bcsd
schemas:
Error:
type: object
description: The error message returned in the response.
properties:
message:
type: string
Label:
type: string
description: 'The application label. Valid values are: `unreviewed`, `approved`, `notApproved`, `underAudit`.'
enum:
- unreviewed
- approved
- notApproved
- underAudit
example: approved
WeightedRisk:
type: string
description: The risk the app poses to the environment.
enum:
- veryLow
- low
- medium
- high
- veryHigh
example: low
AppType:
type: string
description: The type of the app.
enum:
- saas
- paas
- iaas
example: saas
BusinessRisk:
type: string
description: The business risk of the app.
enum:
- veryLow
- low
- medium
- high
- veryHigh
- na
example: na
BulkLabelApplications:
type: object
description: The properties of multiple apps that are updated at the same time.
properties:
timestamp:
type: string
description: The date and time (ISO 8601 timestamp) that the system updated the labels on the applications.
format: date-time
example: '2022-01-01T00:00:00.000Z'
number_of_apps:
type: integer
description: The number of apps updated
example: 25
example:
timestamp: '2022-01-01T00:00:00.000Z'
number_of_apps: 45
UsageType:
type: string
description: 'The type of usage. Valid values are: `personal`, `corporate` (higher risk), or
`indirect` (lower risk, e.g. content delivery network).'
enum:
- indirect
- personal
- corporate
- na
example: na
FinancialViability:
type: string
description: F
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-umbrella/refs/heads/main/openapi/cisco-umbrella-reports-app-discovery-openapi.yml