openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend AgentScores 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: AgentScores
  description: Agent and endpoint experience score monitoring for tracking the health and experience of monitored user devices.
paths:
  /mt/monitor/adem/v1/agents/scores:
    get:
      operationId: getAgentScores
      summary: Palo Alto Networks Get Agent and Endpoint Scores
      description: Returns experience scores for monitored agents and their host endpoints. Each agent score reflects the overall digital experience quality from that user's device including endpoint health, network conditions, and application responsiveness.
      tags:
      - AgentScores
      parameters:
      - name: start_time
        in: query
        description: Start of the time range in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2025-01-28T23:44:20Z'
      - name: end_time
        in: query
        description: End of the time range in ISO 8601 format.
        schema:
          type: string
          format: date-time
        example: '2026-07-14T21:36:35Z'
      - name: time_range
        in: query
        description: Relative time range shorthand.
        schema:
          type: string
          enum:
          - last_1_hour
          - last_4_hours
          - last_24_hours
          - last_7_days
          - last_30_days
        example: last_24_hours
      - name: user_id
        in: query
        description: Filter by user email address or identifier.
        schema:
          type: string
        example: '519732'
      - name: site_name
        in: query
        description: Filter by site name.
        schema:
          type: string
        example: Production Gateway 79
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      responses:
        '200':
          description: Agent scores returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentScore'
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
              examples:
                GetAgentScores200Example:
                  summary: Default getAgentScores 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - timestamp: '2024-03-05T03:27:52Z'
                      agent_id: '771821'
                      user_id: '954963'
                      device_name: Primary Agent 31
                      site_name: Staging Policy 66
                      overall_score: 61
                      endpoint_score: 31
                      network_score: 15
                      cpu_usage_pct: 66.06
                      memory_usage_pct: 24.27
                      sample_count: 361
                    total: 624
                    offset: 1
                    limit: 373
        '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:
  responses:
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid OAuth2 access 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'
  schemas:
    AgentScore:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time bucket for the aggregated score.
          example: '2024-03-05T03:27:52Z'
        agent_id:
          type: string
          description: Unique ADEM agent identifier.
          example: '771821'
        user_id:
          type: string
          description: User identifier associated with the agent.
          example: '954963'
        device_name:
          type: string
          description: Hostname of the endpoint device.
          example: Primary Agent 31
        site_name:
          type: string
          description: Site name where the agent is located.
          example: Staging Policy 66
        overall_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Overall experience score for this agent.
          example: 61
        endpoint_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Endpoint hardware and software health score.
          example: 31
        network_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Network connectivity quality score.
          example: 15
        cpu_usage_pct:
          type: number
          description: CPU usage percentage on the endpoint.
          example: 66.06
        memory_usage_pct:
          type: number
          description: Memory usage percentage on the endpoint.
          example: 24.27
        sample_count:
          type: integer
          description: Number of measurement samples in this time bucket.
          example: 361
    ErrorResponse:
      type: object
      properties:
        _errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: example-code
              message:
                type: string
                example: Firewall incident blocked blocked firewall configured firewall.
              details:
                type: object
                example: {}
          example:
          - code: example-code
            message: Security detected monitoring activity firewall violation activity.
            details: {}
        _request_id:
          type: string
          example: '921009'
  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.