openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Investigations 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: Investigations
  description: Investigation management.
paths:
  /investigations/{id}:
    get:
      operationId: getInvestigation
      summary: Palo Alto Networks Get Investigation
      description: Returns the full details of an investigation including all war room entries, playbook status, and associated incidents.
      tags:
      - Investigations
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the investigation.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Investigation returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
              examples:
                GetInvestigation200Example:
                  summary: Default getInvestigation 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Corporate Agent 49
                    status: 611
                    incidentId: '613705'
                    created: '2025-05-10T09:56:48Z'
                    modified: '2026-07-27T07:59:00Z'
                    entries:
                    - id: example-id
                      investigationId: '215099'
                      type: 140
                      user: example-user
                      created: '2024-07-22T09:20:31Z'
                      modified: '2025-02-16T15:12:04Z'
                      contents: example-contents
                      humanReadable: example-humanReadable
                      tags:
                      - production
                      - pci-scope
                    playbookId: '207029'
                    runningPlaybooks:
                    - example-runningPlaybooks_item
                    - example-runningPlaybooks_item
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /investigation/add:
    post:
      operationId: createInvestigation
      summary: Palo Alto Networks Create Investigation
      description: Creates a new investigation attached to an existing incident. Multiple investigations can be created for a single incident to track separate analytical threads.
      tags:
      - Investigations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - incidentId
              properties:
                incidentId:
                  type: string
                  description: ID of the incident to attach the investigation to.
                name:
                  type: string
                  description: Optional name for the investigation.
            examples:
              CreateInvestigationRequestExample:
                summary: Default createInvestigation request
                x-microcks-default: true
                value:
                  incidentId: '974282'
                  name: Primary Gateway 48
      responses:
        '200':
          description: Investigation created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
              examples:
                CreateInvestigation200Example:
                  summary: Default createInvestigation 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Corporate Agent 49
                    status: 611
                    incidentId: '613705'
                    created: '2025-05-10T09:56:48Z'
                    modified: '2026-07-27T07:59:00Z'
                    entries:
                    - id: example-id
                      investigationId: '215099'
                      type: 140
                      user: example-user
                      created: '2024-07-22T09:20:31Z'
                      modified: '2025-02-16T15:12:04Z'
                      contents: example-contents
                      humanReadable: example-humanReadable
                      tags:
                      - production
                      - pci-scope
                    playbookId: '207029'
                    runningPlaybooks:
                    - example-runningPlaybooks_item
                    - example-runningPlaybooks_item
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Investigation:
      type: object
      description: A Cortex XSOAR investigation containing war room entries and playbook state.
      properties:
        id:
          type: string
          readOnly: true
          example: example-id
        name:
          type: string
          example: Corporate Agent 49
        status:
          type: integer
          example: 611
        incidentId:
          type: string
          example: '613705'
        created:
          type: string
          format: date-time
          example: '2025-05-10T09:56:48Z'
        modified:
          type: string
          format: date-time
          example: '2026-07-27T07:59:00Z'
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'
          example:
          - id: example-id
            investigationId: '215099'
            type: 140
            user: example-user
            created: '2024-07-22T09:20:31Z'
            modified: '2025-02-16T15:12:04Z'
            contents: example-contents
            humanReadable: example-humanReadable
            tags:
            - production
            - pci-scope
        playbookId:
          type: string
          example: '207029'
        runningPlaybooks:
          type: array
          items:
            type: string
          example:
          - example-runningPlaybooks_item
          - example-runningPlaybooks_item
    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
    Entry:
      type: object
      description: A war room entry in a Cortex XSOAR investigation.
      properties:
        id:
          type: string
          readOnly: true
          example: example-id
        investigationId:
          type: string
          example: '215099'
        type:
          type: integer
          description: 'Entry type: 1 (Note), 2 (Download), 3 (File), 4 (Error), 5 (Pinned), 6 (UserManagement), 7 (Image), 8 (PlaygroundCommand), 9 (PlaybookStatusNote), 10 (Canvas), 11 (Widget), 12 (Summary), 13 (Section), 14 (Table).'
          example: 140
        user:
          type: string
          description: Username of the user who created the entry.
          example: example-user
        created:
          type: string
          format: date-time
          example: '2024-07-22T09:20:31Z'
        modified:
          type: string
          format: date-time
          example: '2025-02-16T15:12:04Z'
        contents:
          type: string
          description: Entry content text.
          example: example-contents
        humanReadable:
          type: string
          description: Human-readable formatted content.
          example: example-humanReadable
        tags:
          type: array
          items:
            type: string
          example:
          - production
          - pci-scope
  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.