openapi: 3.1.0
info:
  title: Palo Alto Networks Enterprise DLP API
  description: >-
    REST API for managing Enterprise Data Loss Prevention (DLP) through
    Palo Alto Networks cloud-delivered security services. Provides
    incident detection and management, data pattern configuration,
    and reporting capabilities for monitoring sensitive data exposure
    across network traffic, SaaS applications, and endpoints. Enables
    integration with SIEM, SOAR, and ticketing systems for automated
    incident response workflows. Requires an active Enterprise DLP
    subscription with SASE. Authentication uses OAuth 2.0 Bearer tokens
    from the SASE authentication framework.
  version: '4.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.dlp.paloaltonetworks.com/v4
  description: Enterprise DLP API production server.
security:
- bearerAuth: []
tags:
- name: DataPatterns
  description: Data pattern configuration and lookup operations.
- name: Incidents
  description: DLP incident detection and management operations.
- name: Reports
  description: DLP reporting and summary operations.
paths:
  /incidents:
    get:
      operationId: listIncidents
      summary: Palo Alto Networks List DLP Incidents
      description: >-
        Returns a paginated list of DLP incidents detected across
        monitored channels. Supports filtering by status, severity,
        and time range. Each incident represents a detected occurrence
        of sensitive data matching one or more configured data patterns.
      tags:
      - Incidents
      parameters:
      - name: offset
        in: query
        description: Pagination offset.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of incidents to return.
        schema:
          type: integer
          default: 100
          maximum: 500
        example: 100
      - name: status
        in: query
        description: Filter incidents by current status.
        schema:
          type: string
          enum:
          - open
          - in_review
          - resolved
          - dismissed
        example: in_review
      - name: severity
        in: query
        description: Filter incidents by severity level.
        schema:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
        example: high
      - name: start_time
        in: query
        description: Start of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2025-09-06T05:58:22Z'
      - name: end_time
        in: query
        description: End of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2026-07-24T12:34:37Z'
      responses:
        '200':
          description: DLP incidents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of incidents matching the query.
                  offset:
                    type: integer
                  limit:
                    type: integer
                  incidents:
                    type: array
                    items:
                      $ref: '#/components/schemas/DLPIncident'
              examples:
                ListIncidents200Example:
                  summary: Default listIncidents 200 response
                  x-microcks-default: true
                  value:
                    total: 255
                    offset: 655
                    limit: 245
                    incidents:
                    - incident_id: '579842'
                      status: in_review
                      severity: high
                      data_pattern_name: Staging Policy 73
                      data_pattern_id: '449438'
                      match_count: 11
                      channel: email
                      user: example-user
                      timestamp: '2025-04-23T07:16:37Z'
                      application: web-browsing
                      file_name: Corporate Gateway 41
                      file_type: standard
                      file_size: 130
                      direction: internal
                      action_taken: block
                      reviewer_comments: Traffic violation blocked endpoint suspicious alert.
                      reviewed_by: example-reviewed_by
                      reviewed_at: '2026-03-28T05:36:16Z'
                    - incident_id: '579842'
                      status: in_review
                      severity: high
                      data_pattern_name: Staging Policy 73
                      data_pattern_id: '449438'
                      match_count: 11
                      channel: email
                      user: example-user
                      timestamp: '2025-04-23T07:16:37Z'
                      application: web-browsing
                      file_name: Corporate Gateway 41
                      file_type: standard
                      file_size: 130
                      direction: internal
                      action_taken: block
                      reviewer_comments: Traffic violation blocked endpoint suspicious alert.
                      reviewed_by: example-reviewed_by
                      reviewed_at: '2026-03-28T05:36:16Z'
        '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
  /incidents/{incident_id}:
    get:
      operationId: getIncident
      summary: Palo Alto Networks Get DLP Incident by ID
      description: >-
        Returns detailed information for a specific DLP incident
        including the full data pattern match context, affected file
        or transaction metadata, user attribution, and remediation
        history.
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: '622134'
      responses:
        '200':
          description: DLP incident details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLPIncident'
              examples:
                GetIncident200Example:
                  summary: Default getIncident 200 response
                  x-microcks-default: true
                  value:
                    incident_id: '579842'
                    status: in_review
                    severity: high
                    data_pattern_name: Staging Policy 73
                    data_pattern_id: '449438'
                    match_count: 11
                    channel: email
                    user: example-user
                    timestamp: '2025-04-23T07:16:37Z'
                    application: web-browsing
                    file_name: Corporate Gateway 41
                    file_type: standard
                    file_size: 130
                    direction: internal
                    action_taken: block
                    reviewer_comments: Traffic violation blocked endpoint suspicious alert.
                    reviewed_by: example-reviewed_by
                    reviewed_at: '2026-03-28T05:36:16Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateIncident
      summary: Palo Alto Networks Update DLP Incident
      description: >-
        Updates the status or reviewer comments for a specific DLP
        incident. Used to progress incidents through the investigation
        workflow and to document review findings.
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: '329414'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - open
                  - in_review
                  - resolved
                  - dismissed
                  description: New status for the incident.
                reviewer_comments:
                  type: string
                  description: Comments from the reviewing analyst.
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  status: in_review
                  reviewer_comments: Alert investigation violation detected applied policy incident activity.
      responses:
        '200':
          description: Incident updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLPIncident'
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    incident_id: '579842'
                    status: in_review
                    severity: high
                    data_pattern_name: Staging Policy 73
                    data_pattern_id: '449438'
                    match_count: 11
                    channel: email
                    user: example-user
                    timestamp: '2025-04-23T07:16:37Z'
                    application: web-browsing
                    file_name: Corporate Gateway 41
                    file_type: standard
                    file_size: 130
                    direction: internal
                    action_taken: block
                    reviewer_comments: Traffic violation blocked endpoint suspicious alert.
                    reviewed_by: example-reviewed_by
                    reviewed_at: '2026-03-28T05:36:16Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incidents/{incident_id}/snippets:
    get:
      operationId: getIncidentSnippets
      summary: Palo Alto Networks Get Incident Content Snippets
      description: >-
        Returns content snippets showing the context around data pattern
        matches in the incident. Snippets provide visibility into the
        sensitive data that triggered the DLP policy without returning
        the full document or transaction content. Matched values are
        partially masked by default.
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: '142519'
      responses:
        '200':
          description: Content snippets returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_id:
                    type: string
                    description: Identifier of the parent incident.
                  snippets:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContentSnippet'
              examples:
                GetIncidentSnippets200Example:
                  summary: Default getIncidentSnippets 200 response
                  x-microcks-default: true
                  value:
                    incident_id: '366469'
                    snippets:
                    - pattern_id: '324297'
                      pattern_name: Primary Firewall 23
                      snippet: example-snippet
                      position: 604
                      masked: true
                    - pattern_id: '324297'
                      pattern_name: Primary Firewall 23
                      snippet: example-snippet
                      position: 604
                      masked: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /data-patterns:
    get:
      operationId: listDataPatterns
      summary: Palo Alto Networks List Data Patterns
      description: >-
        Returns a list of configured data patterns used for DLP
        detection. Includes both predefined system patterns (such as
        credit card numbers, social security numbers, and HIPAA
        identifiers) and custom patterns defined by the organization.
        Each pattern includes its detection rules, confidence
        thresholds, and associated data profile assignments.
      tags:
      - DataPatterns
      parameters:
      - name: offset
        in: query
        description: Pagination offset.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of patterns to return.
        schema:
          type: integer
          default: 100
          maximum: 500
        example: 100
      responses:
        '200':
          description: Data patterns returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of data patterns.
                  data_patterns:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataPattern'
              examples:
                ListDataPatterns200Example:
                  summary: Default listDataPatterns 200 response
                  x-microcks-default: true
                  value:
                    total: 693
                    data_patterns:
                    - id: example-id
                      name: Production Gateway 48
                      description: Monitoring violation on alert network activity applied incident monitoring.
                      type: custom
                      category: custom
                      confidence: medium
                      detection_rules: &id001
                      - rule_type: regex
                        value: example-value
                        proximity: 380
                      - rule_type: keyword
                        value: example-value
                        proximity: 94
                      enabled: true
                      incident_count: 23
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /data-patterns/{id}:
    get:
      operationId: getDataPattern
      summary: Palo Alto Networks Get Data Pattern Details
      description: >-
        Returns detailed configuration for a specific data pattern
        including its detection rules, regular expressions or keyword
        lists, proximity settings, and confidence scoring parameters.
      tags:
      - DataPatterns
      parameters:
      - name: id
        in: path
        required: true
        description: Unique data pattern identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Data pattern details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataPattern'
              examples:
                GetDataPattern200Example:
                  summary: Default getDataPattern 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Production Gateway 48
                    description: Monitoring violation on alert network activity applied incident monitoring.
                    type: custom
                    category: custom
                    confidence: medium
                    detection_rules: *id001
                    enabled: true
                    incident_count: 23
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/summary:
    get:
      operationId: getReportSummary
      summary: Palo Alto Networks Get Incident Summary Report
      description: >-
        Returns an aggregated summary of DLP incidents over a specified
        time period. Includes breakdowns by severity, channel, data
        pattern, top users, and trend data. Useful for executive
        reporting and compliance dashboards.
      tags:
      - Reports
      parameters:
      - name: start_time
        in: query
        required: true
        description: Start of reporting period (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2026-09-18T10:51:33Z'
      - name: end_time
        in: query
        required: true
        description: End of reporting period (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2026-11-06T16:58:45Z'
      responses:
        '200':
          description: Incident summary report returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSummary'
              examples:
                GetReportSummary200Example:
                  summary: Default getReportSummary 200 response
                  x-microcks-default: true
                  value:
                    total_incidents: 619
                    open_incidents: 195
                    resolved_incidents: 393
                    by_severity: &id002
                      critical: 30
                      high: 424
                      medium: 932
                      low: 723
                      informational: 986
                    by_channel: &id003
                      web: 358
                      ssl: 453
                      saas: 815
                      email: 786
                      endpoint: 131
                    top_data_patterns: &id004
                    - pattern_name: Production Sensor 38
                      incident_count: 299
                    top_users: &id005
                    - user: example-user
                      incident_count: 609
                    - user: example-user
                      incident_count: 164
                    reporting_period: &id006
                      start_time: '2024-09-15T06:09:00Z'
                      end_time: '2026-07-19T16:10:14Z'
        '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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 bearer token obtained from the Palo Alto Networks
        SASE authentication service using the client credentials flow.
  responses:
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or expired bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DLPIncident:
      type: object
      properties:
        incident_id:
          type: string
          description: Unique incident identifier.
          example: '579842'
        status:
          type: string
          enum:
          - open
          - in_review
          - resolved
          - dismissed
          description: Current incident status.
          example: in_review
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          description: Incident severity level.
          example: high
        data_pattern_name:
          type: string
          description: Name of the data pattern that triggered the incident.
          example: Staging Policy 73
        data_pattern_id:
          type: string
          description: Identifier of the data pattern that triggered the incident.
          example: '449438'
        match_count:
          type: integer
          description: Number of data pattern matches in the content.
          example: 11
        channel:
          type: string
          enum:
          - web
          - ssl
          - saas
          - email
          - endpoint
          description: Channel where the data exposure was detected.
          example: email
        user:
          type: string
          description: Email address or username of the user involved.
          example: example-user
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the incident was detected.
          example: '2025-04-23T07:16:37Z'
        application:
          type: string
          description: Application associated with the incident.
          example: web-browsing
        file_name:
          type: string
          description: Name of the file containing sensitive data.
          example: Corporate Gateway 41
        file_type:
          type: string
          description: MIME type of the file.
          example: standard
        file_size:
          type: integer
          description: Size of the file in bytes.
          example: 130
        direction:
          type: string
          enum:
          - upload
          - download
          - internal
          description: Direction of data movement.
          example: internal
        action_taken:
          type: string
          enum:
          - alert
          - block
          - quarantine
          - encrypt
          description: Automated action taken on the incident.
          example: block
        reviewer_comments:
          type: string
          description: Comments added by the reviewing analyst.
          example: Traffic violation blocked endpoint suspicious alert.
        reviewed_by:
          type: string
          description: Email address of the analyst who reviewed the incident.
          example: example-reviewed_by
        reviewed_at:
          type: string
          format: date-time
          description: Timestamp when the incident was last reviewed.
          example: '2026-03-28T05:36:16Z'
    ContentSnippet:
      type: object
      properties:
        pattern_id:
          type: string
          description: Data pattern identifier that matched.
          example: '324297'
        pattern_name:
          type: string
          description: Data pattern name that matched.
          example: Primary Firewall 23
        snippet:
          type: string
          description: Context snippet around the data pattern match.
          example: example-snippet
        position:
          type: integer
          description: Character offset position of the match within the document.
          example: 604
        masked:
          type: boolean
          description: Whether the matched content within the snippet is masked.
          example: true
    DataPattern:
      type: object
      properties:
        id:
          type: string
          description: Unique data pattern identifier.
          example: example-id
        name:
          type: string
          description: Display name of the data pattern.
          example: Production Gateway 48
        description:
          type: string
          description: Human-readable description of what the pattern detects.
          example: Monitoring violation on alert network activity applied incident monitoring.
        type:
          type: string
          enum:
          - predefined
          - custom
          description: Whether the pattern is predefined or custom.
          example: custom
        category:
          type: string
          description: Pattern category (e.g., PII, PCI, HIPAA, Financial).
          example: custom
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
          description: Confidence threshold for the pattern.
          example: medium
        detection_rules:
          type: array
          items:
            type: object
            properties:
              rule_type:
                type: string
                enum:
                - regex
                - keyword
                - dictionary
                - file_property
                example: dictionary
              value:
                type: string
                example: example-value
              proximity:
                type: integer
                example: 398
          description: Detection rule definitions for the pattern.
          example: *id001
        enabled:
          type: boolean
          description: Whether the data pattern is active.
          example: true
        incident_count:
          type: integer
          description: Total number of incidents triggered by this pattern.
          example: 23
    IncidentSummary:
      type: object
      properties:
        total_incidents:
          type: integer
          description: Total number of incidents in the reporting period.
          example: 619
        open_incidents:
          type: integer
          description: Number of incidents still in open status.
          example: 195
        resolved_incidents:
          type: integer
          description: Number of resolved incidents.
          example: 393
        by_severity:
          type: object
          properties:
            critical:
              type: integer
              example: 256
            high:
              type: integer
              example: 125
            medium:
              type: integer
              example: 374
            low:
              type: integer
              example: 290
            informational:
              type: integer
              example: 50
          description: Incident count breakdown by severity.
          example: *id002
        by_channel:
          type: object
          properties:
            web:
              type: integer
              example: 645
            ssl:
              type: integer
              example: 738
            saas:
              type: integer
              example: 323
            email:
              type: integer
              example: 838
            endpoint:
              type: integer
              example: 664
          description: Incident count breakdown by detection channel.
          example: *id003
        top_data_patterns:
          type: array
          items:
            type: object
            properties:
              pattern_name:
                type: string
                example: Corporate Firewall 91
              incident_count:
                type: integer
                example: 629
          description: Most frequently triggered data patterns.
          example: *id004
        top_users:
          type: array
          items:
            type: object
            properties:
              user:
                type: string
                example: example-user
              incident_count:
                type: integer
                example: 403
          description: Users with the most incidents.
          example: *id005
        reporting_period:
          type: object
          properties:
            start_time:
              type: string
              format: date-time
              example: '2024-04-04T07:15:01Z'
            end_time:
              type: string
              format: date-time
              example: '2024-04-24T08:10:19Z'
          description: Time range for the summary report.
          example: *id006
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code or type.
          example: example-error
        message:
          type: string
          description: Human-readable error message.
          example: Policy blocked rule alert configured traffic Security activity.