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

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'
     #'2023-03-14T18:34:25.412525046Z'

  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'
