openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Playbooks 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: Playbooks
  description: Playbook listing and execution.
paths:
  /playbook:
    get:
      operationId: listPlaybooks
      summary: Palo Alto Networks List Playbooks
      description: Returns all playbooks available in the Cortex XSOAR instance. Playbooks define automated response workflows that execute tasks, run integrations, and perform actions in response to incident conditions.
      tags:
      - Playbooks
      parameters:
      - name: query
        in: query
        description: Filter playbooks by name or keyword.
        schema:
          type: string
        example: example-query
      responses:
        '200':
          description: Playbooks returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Playbook'
              examples:
                ListPlaybooks200Example:
                  summary: Default listPlaybooks 200 response
                  x-microcks-default: true
                  value:
                  - id: example-id
                    name: Production Policy 92
                    version: 797
                    description: Incident blocked suspicious policy violation malware on alert blocked on firewall.
                    tags:
                    - production
                    - pci-scope
                    fromVersion: 6.6.6
                    toVersion: 9.3.8
                    deprecated: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /playbook/run:
    post:
      operationId: runPlaybook
      summary: Palo Alto Networks Run Playbook
      description: Executes a playbook against a specified incident. The playbook runs asynchronously and its progress can be monitored through the investigation's war room entries.
      tags:
      - Playbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - incidentId
              - playbookId
              properties:
                incidentId:
                  type: string
                  description: ID of the incident to run the playbook on.
                playbookId:
                  type: string
                  description: ID of the playbook to execute.
                version:
                  type: integer
                  description: Specific playbook version to run (defaults to latest).
            examples:
              RunPlaybookRequestExample:
                summary: Default runPlaybook request
                x-microcks-default: true
                value:
                  incidentId: '421176'
                  playbookId: '832935'
                  version: 741
      responses:
        '200':
          description: Playbook execution initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Playbook run ID.
                  status:
                    type: string
                    enum:
                    - running
                    - completed
                    - failed
                    - waiting
              examples:
                RunPlaybook200Example:
                  summary: Default runPlaybook 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    status: failed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Playbook:
      type: object
      description: A Cortex XSOAR playbook defining an automated response workflow.
      properties:
        id:
          type: string
          readOnly: true
          example: example-id
        name:
          type: string
          example: Production Policy 92
        version:
          type: integer
          example: 797
        description:
          type: string
          example: Incident blocked suspicious policy violation malware on alert blocked on firewall.
        tags:
          type: array
          items:
            type: string
          example:
          - production
          - pci-scope
        fromVersion:
          type: string
          description: Minimum XSOAR version required.
          example: 6.6.6
        toVersion:
          type: string
          example: 9.3.8
        deprecated:
          type: boolean
          example: true
    ErrorResponse:
      type: object
      properties:
        id:
          type: string
          example: example-id
        status:
          type: integer
          example: 19
        title:
          type: string
          example: Corporate Gateway 74
        detail:
          type: string
          example: example-detail
        error:
          type: string
          example: example-error
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Malformed request or invalid parameters.
      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.