Palo Alto Networks Devices API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Devices 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: Devices
  description: IoT and OT device discovery and profiling operations.
paths:
  /device/list:
    get:
      operationId: listDevices
      summary: Palo Alto Networks List Discovered Devices
      description: Returns a paginated list of IoT and OT devices discovered on the network. Supports filtering by monitoring status and time range. Each device record includes identification details, network information, risk assessment, and classification metadata.
      tags:
      - Devices
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '858936'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of devices to return per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      - name: detail
        in: query
        description: Level of detail to include in the response.
        schema:
          type: string
          enum:
          - full
          - summary
          default: summary
        example: summary
      - name: filter_monitored
        in: query
        description: Filter for monitored or unmonitored devices.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      - name: stime
        in: query
        description: Start time filter as a Unix epoch timestamp in seconds. Returns devices active since this time.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        description: End time filter as a Unix epoch timestamp in seconds. Returns devices active before this time.
        schema:
          type: string
        example: example-etime
      responses:
        '200':
          description: Device list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of devices matching the query.
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
              examples:
                ListDevices200Example:
                  summary: Default listDevices 200 response
                  x-microcks-default: true
                  value:
                    total: 0
                    devices:
                    - deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags: &id001
                      - pci-scope
                    - deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags: *id001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /device/detail:
    get:
      operationId: getDeviceDetail
      summary: Palo Alto Networks Get Device Details
      description: Returns detailed information for the device associated with the specified device identifier. Includes full device profile, risk score breakdown, network activity summary, and classification details.
      tags:
      - Devices
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '904445'
      - name: deviceid
        in: query
        required: true
        description: Unique device identifier.
        schema:
          type: string
        example: '348066'
      responses:
        '200':
          description: Device details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  device:
                    $ref: '#/components/schemas/Device'
              examples:
                GetDeviceDetail200Example:
                  summary: Default getDeviceDetail 200 response
                  x-microcks-default: true
                  value:
                    device:
                      deviceid: '805631'
                      ip: 10.178.141.130
                      mac: 42:f0:fc:53:1d:d1
                      hostname: host-03a3
                      profile: Network Printer
                      category: advanced
                      risk_score: 53
                      os: Ubuntu 22.04
                      os_version: 10.5.0
                      vendor: Fortinet
                      model: VM-300
                      site: Branch-London
                      subnet: 10.32.40.0/24
                      first_seen: '2024-12-19T02:52:11Z'
                      last_seen: '2025-01-24T06:19:11Z'
                      monitored: 'no'
                      confidence_score: 533
                      tags:
                      - pci-scope
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/devices:
    get:
      operationId: listManagedDevices
      summary: Palo Alto Networks List Managed Devices
      description: Returns the inventory of managed devices running the Prisma Access Browser. Includes device platform, browser version, compliance status, and last seen timestamp.
      tags:
      - Devices
      parameters:
      - name: platform
        in: query
        description: Filter devices by operating system platform.
        schema:
          type: string
          enum:
          - windows
          - macos
          - linux
          - chromeos
        example: linux
      - name: compliance_status
        in: query
        description: Filter devices by compliance status.
        schema:
          type: string
          enum:
          - compliant
          - non_compliant
          - unknown
        example: compliant
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of devices to return.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      responses:
        '200':
          description: Managed devices returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ManagedDevice'
              examples:
                ListManagedDevices200Example:
                  summary: Default listManagedDevices 200 response
                  x-microcks-default: true
                  value:
                    total: 241
                    offset: 328
                    limit: 731
                    items:
                    - device_id: '923062'
                      hostname: host-9746
                      platform: windows
                      browser_version: 9.6.7
                      compliance_status: unknown
                      user_id: '942976'
                      last_seen_at: '2025-01-16T12:14:13Z'
                    - device_id: '923062'
                      hostname: host-9746
                      platform: windows
                      browser_version: 9.6.7
                      compliance_status: unknown
                      user_id: '942976'
                      last_seen_at: '2025-01-16T12:14:13Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                ListManagedDevices401Example:
                  summary: Default listManagedDevices 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_2'
              examples:
                ListManagedDevices403Example:
                  summary: Default listManagedDevices 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_2'
              examples:
                ListManagedDevices500Example:
                  summary: Default listManagedDevices 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
components:
  schemas:
    ManagedDevice:
      type: object
      properties:
        device_id:
          type: string
          description: Unique identifier of the managed device.
          example: '923062'
        hostname:
          type: string
          description: Device hostname.
          example: host-9746
        platform:
          type: string
          enum:
          - windows
          - macos
          - linux
          - chromeos
          description: Operating system platform.
          example: windows
        browser_version:
          type: string
          description: Installed Prisma Access Browser version.
          example: 9.6.7
        compliance_status:
          type: string
          enum:
          - compliant
          - non_compliant
          - unknown
          description: Device compliance status.
          example: unknown
        user_id:
          type: string
          description: ID of the last user who logged in on this device.
          example: '942976'
        last_seen_at:
          type: string
          format: date-time
          description: Timestamp of the device's last check-in.
          example: '2025-01-16T12:14:13Z'
    Device:
      type: object
      properties:
        deviceid:
          type: string
          description: Unique device identifier.
          example: '805631'
        ip:
          type: string
          format: ipv4
          description: IPv4 address of the device.
          example: 10.178.141.130
        mac:
          type: string
          description: MAC address of the device.
          example: 42:f0:fc:53:1d:d1
        hostname:
          type: string
          description: Hostname or NetBIOS name of the device.
          example: host-03a3
        profile:
          type: string
          description: Device profile classification (e.g., IP Camera, Infusion Pump).
          example: Network Printer
        category:
          type: string
          description: Device category (e.g., IoT, OT, IT).
          example: advanced
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
          description: Aggregate risk score from 0 (lowest) to 100 (highest).
          example: 53
        os:
          type: string
          description: Detected operating system.
          example: Ubuntu 22.04
        os_version:
          type: string
          description: Detected operating system version.
          example: 10.5.0
        vendor:
          type: string
          description: Device manufacturer or vendor.
          example: Fortinet
        model:
          type: string
          description: Device model identifier.
          example: VM-300
        site:
          type: string
          description: Network site where the device was discovered.
          example: Branch-London
        subnet:
          type: string
          description: Subnet the device belongs to.
          example: 10.32.40.0/24
        first_seen:
          type: string
          format: date-time
          description: Timestamp when the device was first discovered.
          example: '2024-12-19T02:52:11Z'
        last_seen:
          type: string
          format: date-time
          description: Timestamp when the device was last active.
          example: '2025-01-24T06:19:11Z'
        monitored:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Whether the device is currently monitored.
          example: 'no'
        confidence_score:
          type: integer
          description: Confidence level of the device profile classification.
          example: 533
        tags:
          type: array
          items:
            type: string
          description: User-defined or system-assigned tags.
          example:
          - pci-scope
    ErrorResponse:
      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.
    ErrorResponse_2:
      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
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or missing API keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      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.