openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Reports 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: Reports
  description: DLP reporting and summary operations.
paths:
  /reports/summary:
    get:
      operationId: getReportSummary
      summary: Palo Alto Networks Get Incident Summary Report
      description: Returns an aggregated summary of DLP incidents over a specified time period. Includes breakdowns by severity, channel, data pattern, top users, and trend data. Useful for executive reporting and compliance dashboards.
      tags:
      - Reports
      parameters:
      - name: start_time
        in: query
        required: true
        description: Start of reporting period (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2026-09-18T10:51:33Z'
      - name: end_time
        in: query
        required: true
        description: End of reporting period (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2026-11-06T16:58:45Z'
      responses:
        '200':
          description: Incident summary report returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSummary'
              examples:
                GetReportSummary200Example:
                  summary: Default getReportSummary 200 response
                  x-microcks-default: true
                  value:
                    total_incidents: 619
                    open_incidents: 195
                    resolved_incidents: 393
                    by_severity:
                      critical: 30
                      high: 424
                      medium: 932
                      low: 723
                      informational: 986
                    by_channel:
                      web: 358
                      ssl: 453
                      saas: 815
                      email: 786
                      endpoint: 131
                    top_data_patterns:
                    - pattern_name: Production Sensor 38
                      incident_count: 299
                    top_users:
                    - user: example-user
                      incident_count: 609
                    - user: example-user
                      incident_count: 164
                    reporting_period:
                      start_time: '2024-09-15T06:09:00Z'
                      end_time: '2026-07-19T16:10:14Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report/asset:
    get:
      operationId: getAssetReport
      summary: Palo Alto Networks Get Asset Report
      description: Returns an asset inventory report summarizing all discovered IoT and OT devices. The report includes breakdowns by device category, profile, risk level, and site. Useful for asset inventory management and compliance reporting.
      tags:
      - Reports
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '725385'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of report records to return per page.
        schema:
          type: integer
          default: 100
        example: 100
      responses:
        '200':
          description: Asset report returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of assets in the report.
                  report:
                    $ref: '#/components/schemas/AssetReport'
              examples:
                GetAssetReport200Example:
                  summary: Default getAssetReport 200 response
                  x-microcks-default: true
                  value:
                    total: 9
                    report:
                      total_devices: 646
                      monitored_devices: 724
                      by_category: {}
                      by_risk_level:
                        critical: 372
                        high: 696
                        medium: 301
                        low: 206
                      by_site:
                      - site: HQ-SanFrancisco
                        device_count: 327
                      top_profiles:
                      - profile: Network Printer
                        device_count: 597
                      report_time: '2025-03-06T06:54:38Z'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/reports/usage:
    get:
      operationId: getUsageReport
      summary: Palo Alto Networks Get Usage Report
      description: Returns browser usage statistics for the specified time period including active users, session counts, data transferred, blocked threats, and DLP events.
      tags:
      - Reports
      parameters:
      - name: start_date
        in: query
        required: true
        description: Start of the reporting period (ISO 8601).
        schema:
          type: string
          format: date
        example: '2026-10-14'
      - name: end_date
        in: query
        required: true
        description: End of the reporting period (ISO 8601).
        schema:
          type: string
          format: date
        example: '2025-04-14'
      - name: group_by
        in: query
        description: Dimension to group results by.
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - user
          - device
          - policy
        example: week
      responses:
        '200':
          description: Usage report returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReport'
              examples:
                GetUsageReport200Example:
                  summary: Default getUsageReport 200 response
                  x-microcks-default: true
                  value:
                    period:
                      start: '2025-02-09'
                      end: '2025-07-27'
                    active_users: 489
                    total_sessions: 336
                    data_transferred_gb: 1.65
                    threats_blocked: 211
                    dlp_events: 404
                    data_points:
                    - timestamp: '2026-04-05T18:42:10Z'
                      active_users: 55
                      sessions: 417
                    - timestamp: '2025-12-14T19:49:02Z'
                      active_users: 469
                      sessions: 309
        '400':
          description: Invalid date range or query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                GetUsageReport400Example:
                  summary: Default getUsageReport 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                GetUsageReport401Example:
                  summary: Default getUsageReport 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                GetUsageReport403Example:
                  summary: Default getUsageReport 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                GetUsageReport500Example:
                  summary: Default getUsageReport 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /report:
    get:
      operationId: listReports
      summary: Palo Alto Networks List Reports
      description: Returns a list of configured reports including scheduled and on-demand reports for compliance, asset inventory, and alert summaries.
      tags:
      - Reports
      responses:
        '200':
          description: Reports returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Report'
              examples:
                ListReports200Example:
                  summary: Default listReports 200 response
                  x-microcks-default: true
                  value:
                  - id: example-id
                    name: Production Agent 34
                    type: COMPLIANCE
                    status: failed
                    createdOn: 972
                    lastModifiedOn: 196
                    downloadUrl: example-downloadUrl
        '401':
          $ref: '#/components/responses/Unauthorized_3'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse_3:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the error type.
          example: example-error
        message:
          type: string
          description: Human-readable description of the error.
          example: Suspicious detected incident malware activity traffic traffic.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
    UsageReport:
      type: object
      properties:
        period:
          type: object
          properties:
            start:
              type: string
              format: date
              example: '2025-07-03'
            end:
              type: string
              format: date
              example: '2024-01-15'
          example:
            start: '2025-02-09'
            end: '2025-07-27'
        active_users:
          type: integer
          description: Number of unique active users during the period.
          example: 489
        total_sessions:
          type: integer
          description: Total browser sessions started during the period.
          example: 336
        data_transferred_gb:
          type: number
          format: float
          description: Total data transferred through the browser in GB.
          example: 1.65
        threats_blocked:
          type: integer
          description: Number of threats blocked by the browser.
          example: 211
        dlp_events:
          type: integer
          description: Number of DLP policy events triggered.
          example: 404
        data_points:
          type: array
          description: Time-series data points for the report.
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
                example: '2026-04-21T12:03:31Z'
              active_users:
                type: integer
                example: 967
              sessions:
                type: integer
                example: 55
          example:
          - timestamp: '2026-04-05T18:42:10Z'
            active_users: 55
            sessions: 417
          - timestamp: '2025-12-14T19:49:02Z'
            active_users: 469
            sessions: 309
    AssetReport:
      type: object
      properties:
        total_devices:
          type: integer
          description: Total number of discovered devices.
          example: 646
        monitored_devices:
          type: integer
          description: Number of actively monitored devices.
          example: 724
        by_category:
          type: object
          description: Device count breakdown by category.
          additionalProperties:
            type: integer
          example: {}
        by_risk_level:
          type: object
          description: Device count breakdown by risk level.
          properties:
            critical:
              type: integer
              example: 399
            high:
              type: integer
              example: 441
            medium:
              type: integer
              example: 911
            low:
              type: integer
              example: 769
          example:
            critical: 372
            high: 696
            medium: 301
            low: 206
        by_site:
          type: array
          items:
            type: object
            properties:
              site:
                type: string
                example: HQ-SanFrancisco
              device_count:
                type: integer
                example: 930
          description: Device count breakdown by network site.
          example:
          - site: HQ-SanFrancisco
            device_count: 327
        top_profiles:
          type: array
          items:
            type: object
            properties:
              profile:
                type: string
                example: Network Printer
              device_count:
                type: integer
                example: 267
          description: Most common device profiles.
          example:
          - profile: Network Printer
            device_count: 597
        report_time:
          type: string
          format: date-time
          description: Timestamp when the report was generated.
          example: '2025-03-06T06:54:38Z'
    Report:
      type: object
      properties:
        id:
          type: string
          description: Unique report identifier.
          example: example-id
        name:
          type: string
          description: Report name.
          example: Production Agent 34
        type:
          type: string
          description: Report type.
          enum:
          - RIS
          - COMPLIANCE
          - ALERT
          example: COMPLIANCE
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Current report generation status.
          example: failed
        createdOn:
          type: integer
          description: Epoch timestamp when the report was created.
          example: 972
        lastModifiedOn:
          type: integer
          description: Epoch timestamp of last modification.
          example: 196
        downloadUrl:
          type: string
          description: URL for downloading the completed report.
          example: example-downloadUrl
    IncidentSummary:
      type: object
      properties:
        total_incidents:
          type: integer
          description: Total number of incidents in the reporting period.
          example: 619
        open_incidents:
          type: integer
          description: Number of incidents still in open status.
          example: 195
        resolved_incidents:
          type: integer
          description: Number of resolved incidents.
          example: 393
        by_severity:
          type: object
          properties:
            critical:
              type: integer
              example: 256
            high:
              type: integer
              example: 125
            medium:
              type: integer
              example: 374
            low:
              type: integer
              example: 290
            informational:
              type: integer
              example: 50
          description: Incident count breakdown by severity.
          example:
            critical: 30
            high: 424
            medium: 932
            low: 723
            informational: 986
        by_channel:
          type: object
          properties:
            web:
              type: integer
              example: 645
            ssl:
              type: integer
              example: 738
            saas:
              type: integer
              example: 323
            email:
              type: integer
              example: 838
            endpoint:
              type: integer
              example: 664
          description: Incident count breakdown by detection channel.
          example:
            web: 358
            ssl: 453
            saas: 815
            email: 786
            endpoint: 131
        top_data_patterns:
          type: array
          items:
            type: object
            properties:
              pattern_name:
                type: string
                example: Corporate Firewall 91
              incident_count:
                type: integer
                example: 629
          description: Most frequently triggered data patterns.
          example:
          - pattern_name: Production Sensor 38
            incident_count: 299
        top_users:
          type: array
          items:
            type: object
            properties:
              user:
                type: string
                example: example-user
              incident_count:
                type: integer
                example: 403
          description: Users with the most incidents.
          example:
          - user: example-user
            incident_count: 609
          - user: example-user
            incident_count: 164
        reporting_period:
          type: object
          properties:
            start_time:
              type: string
              format: date-time
              example: '2024-04-04T07:15:01Z'
            end_time:
              type: string
              format: date-time
              example: '2024-04-24T08:10:19Z'
          description: Time range for the summary report.
          example:
            start_time: '2024-09-15T06:09:00Z'
            end_time: '2026-07-19T16:10:14Z'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code or type.
          example: example-error
        message:
          type: string
          description: Human-readable error message.
          example: Policy blocked rule alert configured traffic Security activity.
    ErrorResponse_4:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 747
        message:
          type: string
          description: Human-readable error message.
          example: Traffic violation investigation monitoring policy incident applied threat monitoring alert.
        error:
          type: string
          description: Error code.
          example: example-error
    ErrorResponse_2:
      type: object
      properties:
        error:
          type: string
          description: Error code or type.
          example: example-error
        message:
          type: string
          description: Human-readable error message.
          example: Monitoring traffic activity network investigation investigation network policy traffic violation rule rule.
  responses:
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest_2:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
    Unauthorized_2:
      description: Invalid or missing API keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
    Unauthorized_3:
      description: Invalid or expired JWT token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    Unauthorized:
      description: Invalid or expired bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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.