openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Custom Queries 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: Custom Queries
  description: Execute custom data resource queries with filters and aggregations
paths:
  /insights/v3.0/resource/custom-query:
    post:
      operationId: executeCustomQuery
      summary: Palo Alto Networks Execute a Custom Data Resource Query
      description: Execute a flexible custom query against Prisma Access monitoring data with user-defined filters, groupings, and time ranges. Supports advanced analytics use cases that require custom dimension combinations.
      tags:
      - Custom Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomQuery'
            examples:
              ExecuteCustomQueryRequestExample:
                summary: Default executeCustomQuery request
                x-microcks-default: true
                value:
                  resource: example-resource
                  query:
                    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:
        '200':
          description: Custom query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResourceResponse'
              examples:
                ExecuteCustomQuery200Example:
                  summary: Default executeCustomQuery 200 response
                  x-microcks-default: true
                  value:
                    header:
                      requestId: '824026'
                      status: success
                      timestamp: '2024-09-25T11:15:56Z'
                    data:
                    - {}
                    count: 586
                    pagination:
                      offset: 507
                      limit: 195
        '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
components:
  schemas:
    DataResourceResponse:
      type: object
      description: Response containing data resource query results
      properties:
        header:
          type: object
          description: Response metadata
          properties:
            requestId:
              type: string
              description: Unique request identifier
              example: '659112'
            status:
              type: string
              enum:
              - success
              - failed
              - partial
              example: partial
            timestamp:
              type: string
              format: date-time
              example: '2024-10-10T14:49:56Z'
          example:
            requestId: '824026'
            status: success
            timestamp: '2024-09-25T11:15:56Z'
        data:
          type: array
          description: Array of result records
          items:
            type: object
            additionalProperties: true
          example:
          - {}
        count:
          type: integer
          description: Total number of records matching the query
          example: 586
        pagination:
          type: object
          description: Pagination information
          properties:
            offset:
              type: integer
              description: Current result offset
              example: 985
            limit:
              type: integer
              description: Page size
              example: 592
          example:
            offset: 507
            limit: 195
    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
    CustomQuery:
      type: object
      description: Custom query definition with flexible filters
      properties:
        resource:
          type: string
          description: Data resource to query
          example: example-resource
        query:
          $ref: '#/components/schemas/DataResourceQuery'
    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'
    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'
  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.