openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Data Exports 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: Data Exports
  description: Export data resource results for external processing
paths:
  /insights/v3.0/resource/export/{resource_name}:
    post:
      operationId: exportDataResource
      summary: Palo Alto Networks Export Data Resource Results
      description: Export data resource query results for bulk retrieval and external processing. Returns a job ID that can be used to check export status and retrieve the exported data file.
      tags:
      - Data Exports
      parameters:
      - $ref: '#/components/parameters/ResourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataResourceQuery'
            examples:
              ExportDataResourceRequestExample:
                summary: Default exportDataResource request
                x-microcks-default: true
                value:
                  query:
                    properties:
                      time_range:
                        type: RELATIVE
                        value:
                          from: '2024-06-20T21:24:24Z'
                          to: '2025-04-19T12:09:38Z'
                        last:
                          units: DAYS
                          value: 963
                      filter:
                        operator: OR
                        rules:
                        - {}
                        - {}
                  count: 100
                  histogram:
                    property: example-property
                    enabledGranularity: 15_MIN
                  group_by:
                  - example-group_by_item
                  sort:
                    order: asc
                    property: example-property
      responses:
        '202':
          description: Export job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
              examples:
                ExportDataResource202Example:
                  summary: Default exportDataResource 202 response
                  x-microcks-default: true
                  value:
                    job_id: '828854'
                    status: PENDING
                    submitted_at: '2025-09-08T01:27:01Z'
        '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
  /insights/v3.0/resource/export/{job_id}/status:
    get:
      operationId: getExportJobStatus
      summary: Palo Alto Networks Get Export Job Status
      description: Check the status of a previously submitted data resource export job. Returns the current status and a download URL when the export completes.
      tags:
      - Data Exports
      parameters:
      - name: job_id
        in: path
        required: true
        description: Export job identifier returned when the export was submitted
        schema:
          type: string
        example: '202649'
      responses:
        '200':
          description: Export job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobStatus'
              examples:
                GetExportJobStatus200Example:
                  summary: Default getExportJobStatus 200 response
                  x-microcks-default: true
                  value:
                    job_id: '541044'
                    status: COMPLETED
                    download_url: https://login.acme-systems.org/ed2530
                    expires_at: '2025-08-14T12:57:10Z'
                    error_message: example-error_message
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ExportJobResponse:
      type: object
      description: Response from a submitted export job
      properties:
        job_id:
          type: string
          description: Unique identifier for the export job
          example: '828854'
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          description: Current job status
          example: PENDING
        submitted_at:
          type: string
          format: date-time
          description: Job submission timestamp
          example: '2025-09-08T01:27:01Z'
    QueryFilter:
      type: object
      description: Filter criteria for the data resource query
      properties:
        operator:
          type: string
          description: Logical operator for combining filter rules
          enum:
          - AND
          - OR
          example: OR
        rules:
          type: array
          description: List of filter rules
          items:
            type: object
            properties:
              property:
                type: string
                description: Property name to filter on
                example: example-property
              operator:
                type: string
                description: Comparison operator
                enum:
                - equals
                - not_equals
                - contains
                - in
                - not_in
                - greater_than
                - less_than
                example: greater_than
              values:
                type: array
                description: Values to match against
                items:
                  type: string
                example:
                - example-values_item
                - example-values_item
          example:
          - property: example-property
            operator: in
            values:
            - example-values_item
          - property: example-property
            operator: greater_than
            values:
            - example-values_item
    DataResourceQuery:
      type: object
      description: Query parameters for a data resource request
      properties:
        query:
          type: object
          description: Query definition including filters and time range
          properties:
            properties:
              type: object
              description: Property filters for the query
              properties:
                time_range:
                  $ref: '#/components/schemas/TimeRange'
                filter:
                  $ref: '#/components/schemas/QueryFilter'
              example:
                time_range:
                  type: ABSOLUTE
                  value:
                    from: '2026-04-13T06:13:40Z'
                    to: '2026-09-13T19:54:05Z'
                  last:
                    units: HOURS
                    value: 315
                filter:
                  operator: AND
                  rules:
                  - {}
          example:
            properties:
              time_range:
                type: RELATIVE
                value:
                  from: '2024-06-20T21:24:24Z'
                  to: '2025-04-19T12:09:38Z'
                last:
                  units: DAYS
                  value: 963
              filter:
                operator: OR
                rules:
                - {}
                - {}
        count:
          type: integer
          description: Maximum number of results to return
          minimum: 1
          maximum: 1000
          default: 100
          example: 100
        histogram:
          type: object
          description: Histogram aggregation configuration
          properties:
            property:
              type: string
              description: Property to aggregate over
              example: example-property
            enabledGranularity:
              type: string
              enum:
              - 15_MIN
              - 1_HOUR
              - 1_DAY
              description: Time granularity for histogram buckets
              example: 1_DAY
          example:
            property: example-property
            enabledGranularity: 15_MIN
        group_by:
          type: array
          description: Properties to group results by
          items:
            type: string
          example:
          - example-group_by_item
        sort:
          type: object
          description: Sort configuration for results
          properties:
            order:
              type: string
              enum:
              - asc
              - desc
              example: desc
            property:
              type: string
              example: example-property
          example:
            order: asc
            property: example-property
    ExportJobStatus:
      type: object
      description: Status and result of an export job
      properties:
        job_id:
          type: string
          description: Export job identifier
          example: '541044'
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          description: Current job status
          example: COMPLETED
        download_url:
          type: string
          format: uri
          description: Signed URL to download the export file (available when COMPLETED)
          example: https://login.acme-systems.org/ed2530
        expires_at:
          type: string
          format: date-time
          description: Expiration time of the download URL
          example: '2025-08-14T12:57:10Z'
        error_message:
          type: string
          description: Error description if the job failed
          example: example-error_message
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: example-code
            message:
              type: string
              description: Human-readable error description
              example: Malware firewall blocked threat on policy.
          example:
            code: example-code
            message: Network network network network malware monitoring traffic monitoring investigation on suspicious.
    TimeRange:
      type: object
      description: Time range specification for the query
      required:
      - type
      properties:
        type:
          type: string
          description: Type of time range (absolute or relative)
          enum:
          - ABSOLUTE
          - RELATIVE
          example: RELATIVE
        value:
          type: object
          description: Time range value (required for ABSOLUTE type)
          properties:
            from:
              type: string
              format: date-time
              description: Start of the time range (ISO 8601)
              example: '2024-08-09T03:25:39Z'
            to:
              type: string
              format: date-time
              description: End of the time range (ISO 8601)
              example: '2025-11-03T11:39:36Z'
          example:
            from: '2024-09-24T21:35:19Z'
            to: '2026-05-23T17:35:52Z'
        last:
          type: object
          description: Relative time range (required for RELATIVE type)
          properties:
            units:
              type: string
              enum:
              - HOURS
              - DAYS
              - WEEKS
              description: Unit of time for relative range
              example: WEEKS
            value:
              type: integer
              description: Number of units for relative range
              example: 651
          example:
            units: WEEKS
            value: 233
  responses:
    Forbidden:
      description: Forbidden — insufficient permissions for the requested resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found — the requested resource or job does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — missing or invalid access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request — invalid query parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    ResourceName:
      name: resource_name
      in: path
      required: true
      description: The name of the data resource to query. Common resources include `tunnel_status`, `connected_users`, `site_bandwidth`, `app_experience`, `pa_browser_events`, `gp_mobile_users`, `ipsec_tunnels`, `bgp_routes`.
      schema:
        type: string
        enum:
        - tunnel_status
        - connected_users
        - site_bandwidth
        - app_experience
        - pa_browser_events
        - gp_mobile_users
        - ipsec_tunnels
        - bgp_routes
        - alerts
        - sdwan_sites
  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.