Palo Alto Networks Notifications API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Notifications API
  description: AIOps for NGFW Best Practice Assessment (BPA) API. Provides programmatic access to submit BPA requests for Palo Alto Networks next-generation firewalls, check request processing status, and retrieve completed assessment reports. BPA reports analyze firewall configurations against Palo Alto Networks best practices and security benchmarks, identifying gaps and providing remediation guidance to improve security posture. Part of the Strata Cloud Manager platform.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
security:
- oauth2Bearer: []
tags:
- name: Notifications
paths:
  /api/cloud/2.0/agg/notifications/list:
    post:
      tags:
      - Notifications
      summary: Palo Alto Networks List Notifications
      description: "### Overview\n\nList notifications for all child tenants for the current tenant.\n\nThe current tenant TSG ID is extracted from user JWT.\n\nThis is a per-user query.\n\n<u><b>API Body parameters:</b></u>\n\n- filters:\n    - readState - valid values are READ, UNREAD\n    - notifType - UPGRADES, ANNOUNCEMENTS\n    - By default, if no filters are provided then readState is READ and UNREAD and `notifType` is all the values\n- sortByList:\n    - field - valid values are createdTime or impactedTenantCount\n    - sortBy - value values are DESC or ASC"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifListApiReqBody'
            examples:
              All Notifications:
                value:
                  filters:
                  - field: readState
                    values:
                    - READ
                    - UNREAD
                  - field: notifType
                    values:
                    - UPGRADES
                    - ANNOUNCEMENTS
                  sortByList:
                  - field: createdTime
                    sortBy: DESC
              Unread Upgrades:
                value:
                  filters:
                  - field: readState
                    values:
                    - UNREAD
                  - field: notifType
                    values:
                    - UPGRADES
                  sortByList:
                  - field: createdTime
                    sortBy: DESC
              Unread Announcements:
                value:
                  filters:
                  - field: readState
                    values:
                    - UNREAD
                  - field: notifType
                    values:
                    - ANNOUNCEMENTS
                  sortByList:
                  - field: createdTime
                    sortBy: DESC
              Notifications list with Pagination:
                value:
                  filters:
                  - field: readState
                    values:
                    - UNREAD
                  - field: notifType
                    values:
                    - ANNOUNCEMENTS
                  sortByList:
                  - field: createdTime
                    sortBy: DESC
                  page:
                  - num: 0
                    size: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MtNotificationList'
              examples:
                example-0:
                  summary: All Notifications
                  value:
                    data:
                      notificationCounts:
                        readCount: 1
                        unreadCount: 0
                      notificationList:
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Completed
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        id: e8ebd16c-66ab-4113-aa1e-ab274c46322a
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        createdTime: 1698966600461
                        impactedTenantCount: 1
                        readState: READ
                      totalCount: 0
                    requestId: 635d3b26-913a-4451-a5de-0eda8da45040
                example-1:
                  summary: Unread Upgrades
                  value:
                    data:
                      notificationCounts:
                        readCount: 0
                        unreadCount: 0
                      notificationList: []
                      totalCount: 0
                    requestId: 8772a19b-fd60-4640-87b3-2b5e81645b58
                example-2:
                  summary: Unread Announcements
                  value:
                    data:
                      notificationCounts:
                        readCount: 0
                        unreadCount: 0
                      notificationList: []
                      totalCount: 0
                    requestId: 04099fe9-5f9a-4d53-a542-1388931c3a13
                example-3:
                  summary: Notification list with Pagination
                  value:
                    data:
                      notificationCounts:
                        readCount: 0
                        unreadCount: 10
                      notificationList:
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Upcoming
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        id: 44dab57c-e834-48da-a84a-2d1f99adc857
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        createdTime: 1698873900440
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: In Progress
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        id: b3c09288-a69d-42ee-b617-279674ff3ec1
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        createdTime: 1698873900344
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Completed
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        id: 050607cb-a61c-498a-8275-b65672102bbe
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        createdTime: 1698873900325
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Upcoming
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        id: ac0a2269-3a32-4d5b-9552-837275afba1a
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        createdTime: 1698873600215
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: In Progress
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        id: e00e4db4-90a0-4708-a5cc-12b6b4d28c9c
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: In Progress for 1091039496'
                        createdTime: 1698873600121
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Upcoming
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        id: 6477d3d5-b9ef-4ca6-9637-e2ac7f0164b6
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        createdTime: 1698873300631
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Completed
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        id: 5c3b3a0e-1ab6-42e3-afce-28530de13933
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        createdTime: 1698873300526
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Upcoming
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        id: aba778fd-2e97-48bd-a7b8-2bf963316310
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        createdTime: 1698873000205
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Completed
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        id: 123f0890-7eb1-4073-8ed4-4ef71f7a4af1
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Completed for 1091039496'
                        createdTime: 1698873000108
                        impactedTenantCount: 1
                        readState: UNREAD
                      - action: 'Action: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        aggKey:
                          category: Dataplane
                          inAppFlag: true
                          notifType: UPGRADES
                          subCategory: Upcoming
                          tsgId: '1091039496'
                        body: 'Body: Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        id: 4598f13c-8030-4f87-94ea-a0989022457a
                        name: 'Multi-Tenant UPGRADES Notification of Dataplane: Upcoming for 1091039496'
                        createdTime: 1698872700502
                        impactedTenantCount: 1
                        readState: UNREAD
                      totalCount: 4498
                    requestId: d921f075-733e-4091-a060-ef92a16cbfc0
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/cloud/2.0/agg/notifications/list/count:
    post:
      tags:
      - Notifications
      summary: Palo Alto Networks Notification Count
      description: "### Overview\n\nGet notification count with the ability to filter by state or type.\n\nThis is a per-user query.\n\n<u><b>API Body parameters:</b></u>\n\n- filters:\n    - readState - valid values are READ, UNREAD\n    - notifType - UPGRADES, ANNOUNCEMENTS\n    - By default, if no filters are provided then `readState` is READ and UNREAD and `notifType` is all the values"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifListApiReqBody'
            example:
              filters:
              - field: readState
                values:
                - UNREAD
              - field: notifType
                values:
                - UPGRADES
              sortByList:
              - field: createdTime
                sortBy: DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  readCount:
                    type: number
                    description: Number of read notifications
                  unreadCount:
                    type: number
                    description: Number of unread notifications
              example:
                data:
                  readCount: 10
                  unreadCount: 20
                header:
                  createdAt: '2023-09-24T00:42:15Z'
                  clientRequestId: 641b3290-3a3c-4e2e-a6c4-fd9d009c7e14
                  dataCount: 1
                  status:
                    subCode: 200
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/cloud/2.0/agg/notifications/list/state:
    post:
      tags:
      - Notifications
      summary: Palo Alto Networks Set Read State
      description: '### Overview

        Set the `readState` value to READ or UNREAD for the list of notifications specified in the notifIds list in the API body.

        This is a per-user query.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifStateChangeApiBody'
            example:
              notifIds:
              - e8ebd16c-66ab-4113-aa1e-ab274c46322a
              readState: READ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifStateChangeApiBody'
              example:
                data:
                  notifIds:
                  - e8ebd16c-66ab-4113-aa1e-ab274c46322a
                  readState: READ
                requestId: 9e5f8df2-616b-41bc-b928-0f438d715605
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/cloud/2.0/agg/notifications/list/state/{notification-id}:
    get:
      tags:
      - Notifications
      summary: Palo Alto Networks Get Read State
      description: '### Overview


        Get `readState` of the notification whose id specified in the API path parameter.


        This is a per-user query.'
      parameters:
      - name: notification-profile-id
        in: path
        schema:
          type: string
        required: true
        example: '827227'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifStateChangeApiBody'
              example:
                data:
                  aggKey:
                    category: UPGRADES_category1
                    notifType: UPGRADES
                    subCategory: UPGRADES_category1_sub_category
                    tsgId: '1091039496'
                    inAppFlag: true
                  body: body
                  id: '1'
                  impactedTenantCount: 2
                  impactedTenants:
                  - '1091039497'
                  - '1091039496'
                  name: abc
                  channels: []
                  createdTime: 1
                  readState: READ
                requestId: d99c59a0-f271-41b4-b9af-8d7c72829aa6
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    NotifReadState:
      type: string
      description: Read state of the notification
      enum:
      - READ
      - UNREAD
    MtNotifAggKey:
      required:
      - tsgId
      - notifType
      - category
      - subCategory
      - inAppFlag
      type: object
      properties:
        tsgId:
          description: TSG Id
          type: string
          example: '827783'
        notifType:
          description: Notification Type
          type: string
          enum:
          - INCIDENTS
          - UPGRADES
          - ANNOUNCEMENTS
          example: INCIDENTS
        category:
          description: Notification category - is associated with notification type
          type: string
          example: custom
        subCategory:
          description: Notification sub-category - is associated with notification type and notification category
          type: string
          example: custom
        inAppFlag:
          description: InApp Notification Flag
          type: boolean
          example: true
    MtNotification:
      required:
      - name
      - body
      - aggKey
      - notifReadState
      - impactedTenants
      - impactedTenantCount
      - notifChannels
      type: object
      properties:
        id:
          description: Notification id
          type: string
          example: example-id
        name:
          description: Notification name
          type: string
          example: Branch Firewall 10
        body:
          description: Description of the notification
          type: string
          example: example-body
        action:
          description: Action to be taken on receiving the notification (if applicable)
          type: string
          example: deny
        createdTime:
          description: Notification creation time
          type: number
          example: 7.73
        aggKey:
          type: object
          description: Multi-Tenant Notification Aggregation Key
          properties:
            tag:
              $ref: '#/components/schemas/MtNotifAggKey'
          example:
            tag:
              tsgId: '609666'
              notifType: UPGRADES
              category: custom
              subCategory: standard
              inAppFlag: true
        impactedTenants:
          description: List of impacted tenants
          type: array
          items:
            type: string
          example:
          - example-impactedTenants_item
          - example-impactedTenants_item
        impactedTenantCount:
          description: Number of tenants impacted by the multi-tenant notification
          type: number
          example: 19.21
        notifReadState:
          $ref: '#/components/schemas/NotifReadState'
        notifChannels:
          description: List of output channels that the notification is sent on
          type: array
          items:
            $ref: '#/components/schemas/NotifChannel'
          example:
          - name: Staging Firewall 47
            type: EMAIL
            emailChannelDetails: &id001 {}
            webhookChannelDetails: &id002 {}
            template: &id003
              name: Production Policy 39
              templateJson: example-templateJson
          - name: Staging Firewall 47
            type: EMAIL
            emailChannelDetails: *id001
            webhookChannelDetails: *id002
            template: *id003
        notifType:
          description: Notification type
          type: string
          example: advanced
    SortBy:
      type: object
      properties:
        field:
          description: Sort field
          type: string
          enum:
          - createdTime
          - impactedTenantCount
          example: createdTime
        sortBy:
          description: Ascending or Descending
          type: string
          enum:
          - DESC
          - ASC
          example: ASC
    MtNotificationList:
      type: array
      items:
        $ref: '#/components/schemas/MtNotification'
    NotifFilter:
      type: object
      properties:
        field:
          description: Filter field
          type: string
          example: example-field
        values:
          description: Filter field values
          type: array
          items:
            type: string
            enum:
            - readState
            - notifType
            - category
            - subCategory
            - inApp
          example:
          - readState
          - inApp
    NotifChannel:
      required:
      - name
      - type
      type: object
      properties:
        name:
          description: Notification channel name
          type: string
          example: Staging Firewall 47
        type:
          description: Notification channel type
          type: string
          enum:
          - EMAIL
          - WEBHOOK
          example: EMAIL
        emailChannelDetails:
          description: Email channel details
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EmailChannelDetails'
          example: {}
        webhookChannelDetails:
          description: Webhook channel details
          type: object
          additionalProperties:
            $ref: '#/components/schemas/WebhookChannelDetails'
          example: {}
        template:
          description: Channel output template
          type: object
          properties:
            name:
              description: Output channel template name
              type: string
              example: Corporate Agent 74
            templateJson:
              description: JSON describing the output channel template
              type: string
              example: example-templateJson
          example:
            name: Production Policy 39
            templateJson: example-templateJson
    NotifStateChangeApiBody:
      type: object
      properties:
        notifIds:
          description: List of notification IDs
          type: array
          items:
            type: string
          example:
          - example-notifIds_item
          - example-notifIds_item
        readState:
          $ref: '#/components/schemas/NotifReadState'
    EmailDetails:
      required:
      - name
      - emailId
      type: object
      properties:
        name:
          description: Email owner name
          type: string
          example: Branch Gateway 65
        emailId:
          description: Email id
          type: string
          example: '791552'
    EmailChannelDetails:
      required:
      - emails
      type: object
      properties:
        emails:
          description: List of emails
          type: array
          items:
            $ref: '#/components/schemas/EmailDetails'
          example:
          - name: Corporate Agent 40
            emailId: '325822'
    NotifListApiReqBody:
      type: object
      properties:
        filters:
          description: List of output channels that the notification is sent on
          type: array
          items:
            $ref: '#/components/schemas/NotifFilter'
          example:
          - field: example-field
            values:
            - inApp
            - subCategory
        sortByList:
          description: List of output channels that the notification is sent on
          type: array
          items:
            $ref: '#/components/schemas/SortBy'
          example:
          - field: createdTime
            sortBy: ASC
        page:
          type: object
          description: Page number
          properties:
            num:
              type: integer
              description: Page number
              example: 768
            size:
              type: integer
              description: Page size
              example: 169
          example:
            num: 179
            size: 348
    WebhookChannelDetails:
      required:
      - urls
      - authType
      - token
      type: object
      properties:
        urls:
          description: List of Webhook URLs - do not include token in the URL
          type: array
          items:
            type: string
          example:
          - example-urls_item
        authType:
          description: Webhook Authentication Type
          type: string
          enum:
          - NO_AUTH
          - TOKEN
          example: TOKEN
        token:
          description: Webhook token value
          type: string
          example: 2a9211b7e1e46039628e349128c436ce
  securitySchemes:
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.