Cisco Umbrella Application Lists API

openapi: 3.0.1
info:
  title: Cisco Umbrella Application Lists API
  version: 1.0.1
  description: Create and manage the application lists and internet destinations in the application lists for the organization.
  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: policies/v2
tags:
- name: Application Lists
  description: Manage the application lists and the internet destinations in the application lists.
- name: Umbrella
security:
- oauthFlow: []
paths:
  /applicationLists:
    get:
      tags:
      - Application Lists
      - Umbrella
      summary: Get Application Lists
      description: Get the application lists and the number of application lists in the organization.
      operationId: getApplicationLists
      security:
      - oauthFlow:
        - policies.applicationlists:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationLists'
              example:
                count: 3
                results:
                - modifiedAt: '2024-04-04T19:22:53+00:00'
                  applicationListName: New Application List- empty
                  organizationId: 8094936
                  createdAt: '2024-04-04T19:22:53+00:00'
                  applicationListId: 19457
                  isDefault: false
                - applicationCategoryIds: []
                  modifiedAt: '2024-04-04T19:23:17+00:00'
                  applicationListName: New Application List empty
                  organizationId: 8094936
                  createdAt: '2024-04-04T19:23:17+00:00'
                  applicationListId: 19458
                  isDefault: false
                - modifiedAt: '2023-04-10T12:17:03+00:00'
                  applicationListName: custom list
                  organizationId: 8094936
                  createdAt": '2023-03-28T20:32:05+00:00'
                  applicationListId: 14148
                  isDefault: false
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    post:
      tags:
      - Application Lists
      - Umbrella
      summary: Create Application List
      description: Create an application list for the organization.
      operationId: createApplicationList
      security:
      - oauthFlow:
        - policies.applicationlists:write
      requestBody:
        required: true
        description: Create the application list.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationListRequest'
            example:
              applicationCategoryIds: []
              applicationIds:
              - 40
              - 43
              applicationListName: New Application List-5-24-24
              isDefault: false
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
              example:
                applicationCategoryIds: []
                modifiedAt: '2024-05-24T19:22:53+00:00'
                applicationIds:
                - 40
                - 43
                applicationListName: New Application List- empty
                createdAt: '2024-05-24T19:22:53+00:00'
                isDefault: false
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /applicationLists/{applicationListId}:
    get:
      tags:
      - Application Lists
      - Umbrella
      summary: Get Application List
      description: Get the properties of the application list.
      operationId: getApplicationList
      parameters:
      - $ref: '#/components/parameters/applicationListId'
      security:
      - oauthFlow:
        - policies.applicationlists:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
              example:
                applicationCategoryIds: []
                modifiedAt: '2024-05-24T19:22:53+00:00'
                applicationIds:
                - 40
                - 43
                applicationListName: New Application List
                createdAt: '2024-05-24T19:22:53+00:00'
                isDefault: false
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    put:
      tags:
      - Application Lists
      - Umbrella
      summary: Update Application List
      description: Update the properties of the application list.
      operationId: putApplicationList
      parameters:
      - $ref: '#/components/parameters/applicationListId'
      security:
      - oauthFlow:
        - policies.applicationlists:write
      requestBody:
        required: true
        description: Update the application list.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationListRequest'
            example:
              applicationCategoryIds: []
              applicationIds:
              - 40
              - 43
              applicationListName: New Application List- empty
              isDefault: false
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
              example:
                applicationCategoryIds: []
                modifiedAt: '2024-05-24T19:22:53+00:00'
                applicationIds:
                - 40
                - 43
                applicationListName: New Application List- empty
                createdAt: '2024-05-24T19:22:53+00:00'
                isDefault: false
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    delete:
      tags:
      - Application Lists
      - Umbrella
      summary: Delete Application List
      description: Delete the application list in the organization.
      operationId: deleteApplicationList
      parameters:
      - $ref: '#/components/parameters/applicationListId'
      security:
      - oauthFlow:
        - policies.applicationlists:write
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationLists'
              example:
                count: 3
                results:
                - modifiedAt: '2024-04-04T19:22:53+00:00'
                  applicationListName: New Application List- empty
                  organizationId: 8094936
                  createdAt: '2024-04-04T19:22:53+00:00'
                  applicationListId: 19457
                  isDefault: false
                - applicationCategoryIds: []
                  modifiedAt: '2024-04-04T19:23:17+00:00'
                  applicationListName: New Application List empty
                  organizationId: 8094936
                  createdAt: '2024-04-04T19:23:17+00:00'
                  applicationListId: 19458
                  isDefault: false
                - modifiedAt: '2023-04-10T12:17:03+00:00'
                  applicationListName: custom list
                  organizationId: 8094936
                  createdAt": '2023-03-28T20:32:05+00:00'
                  applicationListId: 14148
                  isDefault: false
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /applications/usage:
    get:
      tags:
      - Application Lists
      - Umbrella
      summary: Get Usage of Applications
      description: Get the list of application usage information for the application lists.
      operationId: updateUsageApplications
      parameters:
      - $ref: '#/components/parameters/attributeName'
      - $ref: '#/components/parameters/attributeValue'
      security:
      - oauthFlow:
        - policies.applicationlists:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationUsageResponse'
              example:
              - applicationId: 40
                usedBy:
                  applicationLists:
                  - applicationListId: 15316
                    applicationListName: All Application Selection 3k
                    applicationIds:
                    - 40
                    - 43
                    isRuleAssociated: true
                    usedByRules: []
                  - applicationListId: 14803
                    applicationListName: New Application List - 123
                    applicationIds:
                    - 40
                    - 43
                    isRuleAssociated: true
                    usedByRules: []
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
components:
  headers:
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
    Date:
      schema:
        type: string
        pattern: ^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
  parameters:
    attributeName:
      name: attributeName
      in: query
      description: Filter on the name of the rule attribute.
      required: true
      schema:
        $ref: '#/components/schemas/attributeNameInQuery'
    attributeValue:
      name: attributeValue
      in: query
      description: Filter on the value of the rule attribute.
      required: true
      schema:
        $ref: '#/components/schemas/attributeValueInQuery'
    applicationListId:
      name: applicationListId
      in: path
      description: The ID of the application list.
      required: true
      schema:
        type: integer
  schemas:
    attributeValueInQuery:
      type: string
      description: The comma-separated list of the application IDs.
      items:
        type: integer
      example: 41,51
    attributeNameInQuery:
      type: string
      enum:
      - umbrella.destination.application_ids
      description: The name of the attribute for use in the applications usage query parameter.
      example: umbrella.destination.application_ids
    createdAtApplicationList:
      type: string
      description: The date and time that the system created the application list.
      format: date-time
      readOnly: true
      example: '2021-12-13T16:07:07.222Z'
    modifiedAtApplicationList:
      type: string
      description: The date and time that the system updated the application list.
      format: date-time
      readOnly: true
      example: '2023-11-13T21:28:54+00:00'
    applicationCategoryIds:
      type: array
      description: The list of IDs for the application categories.
      items:
        type: integer
        description: The ID of the application category.
        example: 1235
      example:
      - 353546
    applicationId:
      type: integer
      description: The ID of the application.
      example: 2453454
    applicationIds:
      type: array
      description: The list of IDs for the applications.
      items:
        $ref: '#/components/schemas/applicationId'
      example:
      - 1345
      - 4666
    applicationListId:
      type: integer
      description: The ID of the application list.
      example: 1235
    applicationListName:
      type: string
      description: The descriptive label for the application list.
      example: Application lists on branch_1.
    isDefault:
      type: boolean
      description: Specifies whether the application list is the default application list.
      example: false
    ApplicationLists:
      type: object
      description: The application lists and number of application lists in the organization.
      properties:
        count:
          type: integer
          description: The number of application lists in the organization.
          example: 250
        result:
          type: array
          description: The application lists in the organization.
          items:
            type: object
            description: The properties of the application list.
            properties:
              applicationListId:
                $ref: '#/components/schemas/applicationListId'
              applicationListName:
                $ref: '#/components/schemas/applicationListName'
              isDefault:
                $ref: '#/components/schemas/isDefault'
              createdAt:
                $ref: '#/components/schemas/createdAtApplicationList'
              modifiedAt:
                $ref: '#/components/schemas/modifiedAtApplicationList'
            example:
              modifiedAt: '2024-04-04T19:22:53+00:00'
              applicationListName: New Application List- empty
              organizationId: 8094936
              createdAt: '2024-04-04T19:22:53+00:00'
              applicationListId: 19457
              isDefault: false
          example:
          - modifiedAt: '2024-04-04T19:22:53+00:00'
            applicationListName: New Application List- empty
            organizationId: 8094936
            createdAt: '2024-04-04T19:22:53+00:00'
            applicationListId: 19457
            isDefault: false
      example:
        count: 250
        results:
        - modifiedAt: '2024-04-04T19:22:53+00:00'
          applicationListName: New Application List- empty
          organizationId: 8094936
          createdAt: '2024-04-04T19:22:53+00:00'
          applicationListId: 19457
          isDefault: false
        - modifiedAt: '2024-04-04T19:23:17+00:00'
          applicationListName: New Application List empty
          organizationId: 8094936
          createdAt: '2024-04-04T19:23:17+00:00'
          applicationListId: 19458
          isDefault: false
        - modifiedAt: '2023-04-10T12:17:03+00:00'
          applicationListName: custom list
          organizationId: 8094936
          createdAt: '2023-03-28T20:32:05+00:00'
          applicationListId: 14148
          isDefault: false
    ApplicationList:
      type: object
      description: The properties of the application list.
      properties:
        applicationListName:
          $ref: '#/components/schemas/applicationListName'
        isDefault:
          $ref: '#/components/schemas/isDefault'
        applicationIds:
          $ref: '#/components/schemas/applicationIds'
        applicationCategoryIds:
          $ref: '#/components/schemas/applicationCategoryIds'
        createdAt:
          $ref: '#/components/schemas/createdAtApplicationList'
        modifiedAt:
          $ref: '#/components/schemas/modifiedAtApplicationList'
      example:
        applicationCategoryIds: []
        applicationIds: []
        applicationListName: New Application List- empty
        isDefault: false
        createdAt: '2024-04-04T19:23:17+00:00'
        modifiedAt: '2023-04-10T12:17:03+00:00'
    ApplicationListRequest:
      type: object
      description: The properties of the application list.
      required:
      - applicationListName
      - applicationIds
      - isDefault
      properties:
        applicationListName:
          $ref: '#/components/schemas/applicationListName'
        isDefault:
          $ref: '#/components/schemas/isDefault'
        applicationIds:
          $ref: '#/components/schemas/applicationIds'
        applicationCategoryIds:
          $ref: '#/components/schemas/applicationCategoryIds'
      example:
        applicationCategoryIds: []
        applicationIds: []
        applicationListName: New Application List- empty
        isDefault: false
    ApplicationUsageResponse:
      type: array
      description: 'The list of application usage information.

        The application usage information describes the relationships between the application and its application lists and
        access rules.'
      items:
        type: object
        description: The information about the application usage.
        properties:
          applicationId:
            $ref: '#/components/schemas/applicationId'
          usedBy:
            type: object
            description: The properties of the application lists that include the applications.
            properties:
              applicationLists:
                type: array
                description: The list of application list information.
                items:
                  type: object
                  description: The properties of the application List.
                  properties:
                    applicationListId:
                      $ref: '#/components/schemas/applicationListId'
                    usedByRules:
                      type: array
                      description: The list of rule IDs that include the applications.
                      items:
                        type: integer
                        description: The ID of the rule.
                        example: 13455
                      example:
                      - 13434
                      - 55666
                    applicationListName:
                      $ref: '#/components/schemas/applicationListName'
                    applicationIds:
                      $ref: '#/components/schemas/applicationIds'
                    isRuleAssociated:
                      type: boolean
                      description: Specifies whether the application list is associated with an access rule.
                      example: false
                  example:
                    applicationListId: 134
                    usedByRules:
                    - 13456
                    - 45455
                    applicationListName: The name of the application list.
                    applicationIds:
                    - 40
                    - 43
                    isRuleAssociated: true
                example:
                - applicationListId: 134
                  usedByRules:
                  - 13456
                  - 45455
                  applicationListName: The name of the application list.
                  applicationIds:
                  - 40
                  - 43
                  isRuleAssociated: true
            example:
              applicationLists:
              - applicationListId: 134
                usedByRules:
                - 13456
                - 45455
                applicationListName: The name of the application list.
                applicationIds:
                - 40
                - 43
                isRuleAssociated: true
        example:
          applicationId: 40
          usedBy:
            applicationLists:
            - applicationListId: 134
              usedByRules:
              - 13456
              - 45455
              applicationListName: The name of the application list.
              applicationIds:
              - 40
              - 43
              isRuleAssociated: true
      example:
      - applicationId: 40
        usedBy:
          applicationLists:
          - applicationListId: 15316
            applicationListName: All Application Selection 3k
            applicationIds:
            - 40
            - 43
            isRuleAssociated: true
            usedByRules: []
          - applicationListId: 14803
            applicationListName: New Application List - 123
            applicationIds:
            - 40
            - 43
            isRuleAssociated: true
            usedByRules: []
      - applicationId: 43
        usedBy:
          applicationLists:
          - applicationListId: 15316
            applicationListName: All Application Selection 3k
            applicationIds:
            - 40
            - 43
            isRuleAssociated: false
            usedByRules: []
          - applicationListId: 14803
            applicationListName: New Application List - 123
            applicationIds:
            - 40
            - 43
            isRuleAssociated: false
            usedByRules: []
  responses:
    400Error:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message explaining the reason for failure.
                example: The organization ID is a numeric value.
              requestId:
                type: string
                description: The ID of the request.
                example: 7d318524-d5a4-4fd8-8b29-ad295b2f035b
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    401Error:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message explaining the reason for failure.
                example: Authorization token is invalid.
              requestId:
                type: string
                description: The ID of the request.
                example: 7d318524-d5a4-4fd8-8b29-ad295b2f035b
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message explaining the reason for failure.
                example: Not Authorized
              requestId:
                type: string
                description: The ID of the request.
                example: 7d318524-d5a4-4fd8-8b29-ad295b2f035b
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message explaining the reason for failure.
                example: Not Found
              requestId:
                type: string
                description: The ID of the request.
                example: 7d318524-d5a4-4fd8-8b29-ad295b2f035b
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    500Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message explaining the reason for failure.
                example: Internal Server Error
              requestId:
                type: string
                description: The ID of the request.
                example: 7d318524-d5a4-4fd8-8b29-ad295b2f035b
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: The client credential flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            policies.applicationlists:write: Write policies application lists
            policies.applicationlists:read: Read policies application lists
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/application-lists-internet-umb.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/application-lists-internet-umb.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/