openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Alerts 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: Alerts
  description: Alert retrieval and management.
paths:
  /alerts/get_alerts:
    post:
      operationId: getAlerts
      summary: Palo Alto Networks Get Alerts
      description: Returns alerts matching the specified filter criteria. Alerts represent individual detections from endpoint, network, or cloud data sources. Supports filtering by alert ID, severity, category, and timestamp.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAlertsRequestExample:
                summary: Default getAlerts request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Alerts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      alerts:
                        type: array
                        items:
                          $ref: '#/components/schemas/Alert'
              examples:
                GetAlerts200Example:
                  summary: Default getAlerts 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 56
                      result_count: 969
                      alerts:
                      - alert_id: '999423'
                        detection_timestamp: 1733555086833
                        name: Staging Policy 70
                        category: custom
                        description: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
                        host_ip: &id001
                        - example-host_ip_item
                        - example-host_ip_item
                        host_name: Corporate Agent 14
                        user_name: jsmith
                        mac: &id002
                        - example-mac_item
                        source: example-source
                        action: alert
                        action_pretty: alert
                        severity: informational
                        matching_status: running
                        alert_type: standard
                        resolution_status: enabled
                        resolution_comment: Monitoring threat applied Security investigation Security configured.
                      - alert_id: '999423'
                        detection_timestamp: 1733555086833
                        name: Staging Policy 70
                        category: custom
                        description: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
                        host_ip: *id001
                        host_name: Corporate Agent 14
                        user_name: jsmith
                        mac: *id002
                        source: example-source
                        action: alert
                        action_pretty: alert
                        severity: informational
                        matching_status: running
                        alert_type: standard
                        resolution_status: enabled
                        resolution_comment: Monitoring threat applied Security investigation Security configured.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/list:
    get:
      operationId: listAlerts
      summary: Palo Alto Networks List Security Alerts
      description: Returns a paginated list of security alerts generated by the IoT Security service. Alerts are triggered by anomalous device behavior, policy violations, known vulnerability exploitation, and communication with suspicious destinations. Supports filtering by resolution status and time range.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '758970'
      - name: offset
        in: query
        description: Pagination offset for results.
        schema:
          type: integer
          default: 0
        example: 0
      - name: pagelength
        in: query
        description: Number of alerts to return per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
        example: 100
      - name: stime
        in: query
        description: Start time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        description: End time filter as a Unix epoch timestamp in seconds.
        schema:
          type: string
        example: example-etime
      - name: resolved
        in: query
        description: Filter by alert resolution status.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      responses:
        '200':
          description: Alert list returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of alerts matching the query.
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert_3'
              examples:
                ListAlerts200Example:
                  summary: Default listAlerts 200 response
                  x-microcks-default: true
                  value:
                    total: 701
                    alerts:
                    - id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: {}
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/detail:
    get:
      operationId: getAlertDetail
      summary: Palo Alto Networks Get Alert Details
      description: Returns detailed information for a specific security alert by its identifier. Includes full alert context, affected device information, timeline, and recommended response actions.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '272345'
      - name: id
        in: query
        required: true
        description: Unique alert identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Alert details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alert:
                    $ref: '#/components/schemas/Alert_3'
              examples:
                GetAlertDetail200Example:
                  summary: Default getAlertDetail 200 response
                  x-microcks-default: true
                  value:
                    alert:
                      id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: {}
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/update:
    put:
      operationId: updateAlert
      summary: Palo Alto Networks Update Alert Status
      description: Updates the resolution status of a specific security alert. Allows marking an alert as resolved or unresolved, and provides a reason for the status change. Resolved alerts are retained for historical analysis.
      tags:
      - Alerts
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer tenant identifier.
        schema:
          type: string
        example: '582063'
      - name: id
        in: query
        required: true
        description: Unique alert identifier to update.
        schema:
          type: string
        example: example-id
      - name: resolved
        in: query
        required: true
        description: New resolution status for the alert.
        schema:
          type: string
          enum:
          - 'yes'
          - 'no'
        example: 'no'
      - name: reason
        in: query
        description: Reason for the status change.
        schema:
          type: string
        example: Firewall Security Security alert Security applied suspicious violation rule applied alert.
      responses:
        '200':
          description: Alert status updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the update was successful.
                  alert:
                    $ref: '#/components/schemas/Alert_3'
              examples:
                UpdateAlert200Example:
                  summary: Default updateAlert 200 response
                  x-microcks-default: true
                  value:
                    success: false
                    alert:
                      id: example-id
                      type: advanced
                      severity: info
                      description: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
                      deviceid: '257277'
                      device_ip: 10.156.198.91
                      device_profile: Network Printer
                      resolved: 'no'
                      resolved_reason: example-resolved_reason
                      timestamp: '2024-05-28T18:45:09Z'
                      details: {}
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert:
    get:
      operationId: getAlerts
      summary: Palo Alto Networks List Alerts
      description: Returns security alerts matching the specified filters. Supports filtering by status, severity, policy, time range, cloud type, and account. The timeType, timeAmount, and timeUnit parameters control the time range filter for relative time windows.
      tags:
      - Alerts
      parameters:
      - name: timeType
        in: query
        description: Time filter type.
        schema:
          type: string
          enum:
          - relative
          - absolute
          - to_now
        example: relative
      - name: timeAmount
        in: query
        description: Time amount for relative time type.
        schema:
          type: integer
        example: 629
      - name: timeUnit
        in: query
        description: Time unit for relative time type.
        schema:
          type: string
          enum:
          - minute
          - hour
          - day
          - week
          - month
          - year
        example: month
      - name: startTime
        in: query
        description: Start time in epoch milliseconds for absolute time type.
        schema:
          type: integer
        example: 1730951626179
      - name: endTime
        in: query
        description: End time in epoch milliseconds for absolute time type.
        schema:
          type: integer
        example: 1722147834745
      - name: limit
        in: query
        description: Maximum number of alerts to return.
        schema:
          type: integer
          default: 10000
        example: 10000
      - name: offset
        in: query
        description: Pagination offset.
        schema:
          type: integer
          default: 0
        example: 0
      - name: severity
        in: query
        description: Filter by alert severity.
        schema:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
        example: critical
      - name: policy.id
        in: query
        description: Filter alerts by policy identifier.
        schema:
          type: string
        example: '750350'
      - name: detailed
        in: query
        description: Include full alert details.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Alerts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalRows:
                    type: integer
                    description: Total number of alerts matching filters.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert_4'
              examples:
                GetAlerts200Example:
                  summary: Default getAlerts 200 response
                  x-microcks-default: true
                  value:
                    totalRows: 424
                    items:
                    - id: example-id
                      status: open
                      reason: Firewall detected monitoring incident activity traffic blocked endpoint incident alert.
                      firstSeen: 725
                      lastSeen: 266
                      alertTime: 684
                      policy:
                        policyId: '936608'
                        policyType: custom
                        name: Primary Gateway 71
                        severity: high
                        recommendation: example-recommendation
                      resource:
                        rrn: example-rrn
                        id: example-id
                        name: Staging Agent 24
                        cloudType: custom
                        accountId: '699331'
                        accountName: Staging Policy 89
                        regionId: '252983'
                        resourceType: custom
                      riskDetail:
                        score: 776
                        rating: example-rating
        '400':
          $ref: '#/components/responses/BadRequest_3'
        '401':
          $ref: '#/components/responses/Unauthorized_3'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/{id}:
    get:
      operationId: getAlert
      summary: Palo Alto Networks Get Alert Details
      description: Returns full details for a specific security alert.
      tags:
      - Alerts
      parameters:
      - name: id
        in: path
        required: true
        description: Unique alert identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Alert details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert_4'
              examples:
                GetAlert200Example:
                  summary: Default getAlert 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    status: open
                    reason: Firewall detected monitoring incident activity traffic blocked endpoint incident alert.
                    firstSeen: 725
                    lastSeen: 266
                    alertTime: 684
                    policy:
                      policyId: '936608'
                      policyType: custom
                      name: Primary Gateway 71
                      severity: high
                      recommendation: example-recommendation
                    resource:
                      rrn: example-rrn
                      id: example-id
                      name: Staging Agent 24
                      cloudType: custom
                      accountId: '699331'
                      accountName: Staging Policy 89
                      regionId: '252983'
                      resourceType: custom
                    riskDetail:
                      score: 776
                      rating: example-rating
        '401':
          $ref: '#/components/responses/Unauthorized_3'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound_2'
        '500':
          $ref: '#/components/responses/InternalServerError_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/dismiss:
    post:
      operationId: dismissAlerts
      summary: Palo Alto Networks Dismiss Alerts
      description: Dismisses one or more security alerts with a reason and optional note.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - alerts
              - dismissalNote
              properties:
                alerts:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                  description: List of alert IDs to dismiss.
                dismissalNote:
                  type: string
                  description: Reason for dismissal.
                dismissalTimeRange:
                  $ref: '#/components/schemas/TimeRange'
                filter:
                  type: object
                  properties:
                    timeRange:
                      $ref: '#/components/schemas/TimeRange'
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/AlertFilter'
            examples:
              DismissAlertsRequestExample:
                summary: Default dismissAlerts request
                x-microcks-default: true
                value:
                  alerts:
                  - id: example-id
                  dismissalNote: example-dismissalNote
                  dismissalTimeRange:
                    type: to_now
                    value: &id003
                      amount: 301
                      unit: year
                  filter:
                    timeRange:
                      type: to_now
                      value: *id003
                    filters:
                    - name: Staging Agent 23
                      operator: '='
                      value: example-value
                    - name: Staging Agent 23
                      operator: '='
                      value: example-value
      responses:
        '200':
          description: Alerts dismissed successfully.
        '400':
          $ref: '#/components/responses/BadRequest_3'
        '401':
          $ref: '#/components/responses/Unauthorized_3'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /alert/reopen:
    post:
      operationId: reopenAlerts
      summary: Palo Alto Networks Reopen Dismissed Alerts
      description: Reopens one or more previously dismissed alerts, restoring them to open status for active review.
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - alerts
              properties:
                alerts:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                  description: List of dismissed alert IDs to reopen.
            examples:
              ReopenAlertsRequestExample:
                summary: Default reopenAlerts request
                x-microcks-default: true
                value:
                  alerts:
                  - id: example-id
      responses:
        '200':
          description: Alerts reopened successfully.
        '400':
          $ref: '#/components/responses/BadRequest_3'
        '401':
          $ref: '#/components/responses/Unauthorized_3'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError_2'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dspm/api/v1/alerts:
    get:
      operationId: listDataSecurityAlerts
      summary: Palo Alto Networks List Data Security Alerts
      description: Returns data security alerts generated when sensitive data exposure conditions are detected. Alerts are triggered by new public data store discoveries, anomalous data access patterns, policy violations, and newly identified sensitive data in previously clean data stores.
      tags:
      - Alerts
      parameters:
      - name: offset
        in: query
        description: Number of records to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of records to return.
        schema:
          type: integer
          default: 25
        example: 25
      - name: severity
        in: query
        description: Filter alerts by severity level.
        schema:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
        example: critical
      - name: status
        in: query
        description: Filter by alert status.
        schema:
          type: string
          enum:
          - open
          - dismissed
          - resolved
        example: dismissed
      - name: cloudProvider
        in: query
        description: Filter by cloud provider.
        schema:
          type: string
          enum:
          - aws
          - azure
          - gcp
        example: azure
      - name: start_time
        in: query
        description: Start of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2025-05-15T20:05:55Z'
      - name: end_time
        in: query
        description: End of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2024-06-25T20:37:39Z'
      responses:
        '200':
          description: Data security alerts returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalCount:
                    type: integer
                    description: Total number of alerts matching filters.
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataSecurityAlert'
              examples:
                ListDataSecurityAlerts200Example:
                  summary: Default listDataSecurityAlerts 200 response
                  x-microcks-default: true
                  value:
                    totalCount: 663
                    alerts:
                    - id: example-id
                      title: Staging Gateway 49
                      description: Applied Security suspicious Security activity incident endpoint rule violation monitoring configured policy.
                      severity: high
                      status: dismissed
                      alertType: accessAnomaly
                      dataStoreId: '172843'
                      dataStoreName: Primary Gateway 98
                      cloudProvider: aws
                      cloudAccountId: '796638'
                      region: us-west-2
                      affectedClassifications:
                      - example-affectedClassifications_item
                      - example-affectedClassifications_item
                      detectedAt: '2026-06-24T13:35:39Z'
                      resolvedAt: '2025-06-12T03:49:03Z'
        '400':
          $ref: '#/components/responses/BadRequest_4'
        '401':
          $ref: '#/components/responses/Unauthorized_4'
        '403':
          $ref: '#/components/responses/Forbidden_2'
        '500':
          $ref: '#/components/responses/InternalServerError_3'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AlertFilter:
      type: object
      properties:
        name:
          type: string
          description: Filter field name (e.g., alert.status, cloud.type, policy.severity, cloud.accountId).
          example: Staging Agent 23
        operator:
          type: string
          enum:
          - '='
          example: '='
        value:
          type: string
          example: example-value
    Alert_4:
      type: object
      properties:
        id:
          type: string
          description: Unique alert identifier.
          example: example-id
        status:
          type: string
          enum:
          - open
          - dismissed
          - snoozed
          - resolved
          description: Current alert status.
          example: open
        reason:
          type: string
          description: Reason for the current alert status.
          example: Firewall detected monitoring incident activity traffic blocked endpoint incident alert.
        firstSeen:
          type: integer
          description: Epoch timestamp in milliseconds when the alert was first generated.
          example: 725
        lastSeen:
          type: integer
          description: Epoch timestamp in milliseconds when the alert was last seen.
          example: 266
        alertTime:
          type: integer
          description: Epoch timestamp in milliseconds of the alert.
          example: 684
        policy:
          type: object
          properties:
            policyId:
              type: string
              example: '803871'
            policyType:
              type: string
              example: custom
            name:
              type: string
              example: Branch Firewall 19
            severity:
              type: string
              enum:
              - critical
              - high
              - medium
              - low
              - informational
              example: informational
            recommendation:
              type: string
              example: example-recommendation
          description: Policy that generated this alert.
          example:
            policyId: '936608'
            policyType: custom
            name: Primary Gateway 71
            severity: high
            recommendation: example-recommendation
        resource:
          type: object
          properties:
            rrn:
              type: string
              description: Prisma Cloud Resource RRN.
              example: example-rrn
            id:
              type: string
              example: example-id
            name:
              type: string
              example: Primary Sensor 65
            cloudType:
              type: string
              example: advanced
            accountId:
              type: string
              example: '336404'
            accountName:
              type: string
              example: Corporate Agent 04
            regionId:
              type: string
              example: '751072'
            resourceType:
              type: string
              example: custom
          description: Cloud resource associated with the alert.
          example:
            rrn: example-rrn
            id: example-id
            name: Staging Agent 24
            cloudType: custom
            accountId: '699331'
            accountName: Staging Policy 89
            regionId: '252983'
            resourceType: custom
        riskDetail:
          type: object
          properties:
            score:
              type: integer
              example: 270
            rating:
              type: string
              example: example-rating
          example:
            score: 776
            rating: example-rating
    ErrorResponse:
      type: object
      properties:
        reply:
          type: object
          properties:
            err_code:
              type: integer
              example: 782
            err_msg:
              type: string
              example: example-err_msg
            err_extra:
              type: string
              example: example-err_extra
          example:
            err_code: 270
            err_msg: example-err_msg
            err_extra: example-err_extra
    Alert_3:
      type: object
      properties:
        id:
          type: string
          description: Unique alert identifier.
          example: example-id
        type:
          type: string
          description: Alert type classification.
          example: advanced
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - info
          description: Alert severity level.
          example: info
        description:
          type: string
          description: Human-readable alert description.
          example: Firewall incident network violation detected incident alert monitoring traffic monitoring rule.
        deviceid:
          type: string
          description: Identifier of the affected device.
          example: '257277'
        device_ip:
          type: string
          format: ipv4
          description: IP address of the affected device.
          example: 10.156.198.91
        device_profile:
          type: string
          description: Profile of the affected device.
          example: Network Printer
        resolved:
          type: string
          enum:
          - 'yes'
          - 'no'
          description: Whether the alert has been resolved.
          example: 'no'
        resolved_reason:
          type: string
          description: Resolution reason if resolved.
          example: example-resolved_reason
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the alert was generated.
          example: '2024-05-28T18:45:09Z'
        details:
          type: object
          description: Additional alert-specific details.
          example: {}
    TimeRange:
      type: object
      properties:
        type:
          type: string
          enum:
          - relative
          - absolute
          - to_now
          example: to_now
        value:
          type: object
          properties:
            amount:
              type: integer
              example: 810
            unit:
              type: string
              enum:
              - minute
              - hour
              - day
              - week
              - month
              - year
              example: week
          example:
            amount: 301
            unit: year
    Filter:
      type: object
      description: A filter criterion for querying XDR resources.
      required:
      - field
      - operator
      - value
      properties:
        field:
          type: string
          description: Field name to filter on (e.g., incident_id, status, severity).
          example: example-field
        operator:
          type: string
          enum:
          - in
          - contains
          - gte
          - lte
          - eq
          - neq
          description: Comparison operator.
          example: lte
        value:
          description: Filter value. Use an array for the "in" operator, a string or integer for others.
          oneOf:
          - type: string
          - type: integer
          - type: array
            items:
              oneOf:
              - type: string
              - type: integer
          example: example-value
    SortOrder:
      type: object
      description: Sorting specification for result sets.
      properties:
        field:
          type: string
          description: Field to sort by.
          example: example-field
        keyword:
          type: string
          enum:
          - asc
          - desc
          description: Sort direction.
          example: asc
    Alert:
      type: object
      description: A Cortex XDR alert representing a single detection event.
      properties:
        alert_id:
          type: string
          example: '999423'
        detection_timestamp:
          type: integer
          description: Detection timestamp as Unix epoch milliseconds.
          example: 1733555086833
        name:
          type: string
          description: Alert name or rule name that triggered this alert.
          example: Staging Policy 70
        category:
          type: string
          description: Alert category (e.g., Malware, Exploit, Lateral Movement).
          example: custom
        description:
          type: string
          example: Rule incident incident firewall suspicious monitoring activity threat rule monitoring suspicious detected.
        host_ip:
          type: array
          items:
            type: string
          example:
          - example-host_ip_item
          - example-host_ip_item
        host_name:
          type: string
          example: Corporate Agent 14
        user_name:
          type: string
          example: jsmith
        mac:
          type: array
          items:
            type: string
          example:
          - example-mac_item
        source:
          type: string
          description: Data source that generated the alert.
          example: example-source
        action:
          type: string
          description: Action taken on the alert.
          example: alert
        action_pretty:
          type: string
          example: alert
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          - unknown
          example: informational
        matching_status:
          type: string
          example: running
        alert_type:
          type: string
          example: standard
        resolution_status:
          type: string
          example: enabled
        resolution_comment:
          type: string
          example: Monitoring threat applied Security investigation Security configured.
    DataSecurityAlert:
      type: object
      properties:
        id:
          type: string
          description: Unique alert identifier.
          example: example-id
        title:
          type: string
          description: Short description of the alert condition.
          example: Staging Gateway 49
        description:
          type: string
          description: Detailed alert description.
          example: Applied Security suspicious Security activity incident endpoint rule violation monitoring configured policy.
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          description: Alert severity level.
          example: high
        status:
          type: string
          enum:
          - open
          - dismissed
          - resolved
          description: Current alert status.
          example: dismissed
        alertType:
          type: string
          description: Category of data security alert.
          enum:
          - newPublicDataStore
          - newSensitiveData
          - accessAnomaly
          - policyViolation
          - dataExfiltration
          example: accessAnomaly
        dataStoreId:
          type: string
          description: Affected data store identifier.
          example: '172843'
        dataStoreName:
          type: string
          description: Name of the affected data store.
          example: Primary Gateway 98
        cloudProvider:
          type: string
          enum:
          - aws
          - azure
          - gcp
          description: Cloud provider of the affected data store.
          example: aws
        cloudAccountId:
          type: string
          description: Cloud account identifier.
          example: '796638'
        region:
          type: string
          description: Cloud region of the affected data store.
          example: us-west-2
        affectedClassifications:
          type: array
          items:
            type: string
          description: Data classification labels involved in the alert.
          example:
          - example-affectedClassifications_item
          - example-affectedClassifications_item
        detectedAt:
          type: string
          format: date-time
          description: Timestamp when the alert was generated.
          example: '2026-06-24T13:35:39Z'
        resolvedAt:
          type: string
          format: date-time
          description: Timestamp when the alert was resolved. Null if still open.
          example: '2025-06-12T03:49:03Z'
    ErrorResponse_3:
      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_4:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 747
        message:
          type: string
          description: Human-readable error message.
          example: Traffic violation investigation monitoring policy incident applied threat monitoring alert.
        error:
          type: string
          description: Error code.
          example: example-error
    ErrorResponse_5:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 177
        message:
          type: string
          description: Human-readable error message.
          example: Suspicious traffic configured monitoring malware endpoint applied.
        error:
          type: string
          description: Error code.
          example: example-error
  responses:
    BadRequest_2:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_3'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_3'
    InternalServerError_2:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    Forbidden_2:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_5'
    BadRequest_3:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    Unauthorized_3:
      description: Invalid or expired JWT token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    InternalServerError_3:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_5'
    Unauthorized_2:
      description: Invalid or missing API keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_3'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_3'
    Unauthorized_4:
      description: Invalid or expired JWT token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_5'
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    Unauthorized:
      description: Missing or invalid authentication headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest_4:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_5'
    NotFound_2:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_4'
    BadRequest:
      description: Malformed request body 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.