Palo Alto Networks Email DLP API API

openapi: 3.2.0
info:
  contact: {}
  description: 'Programmatically request [Email incidents](https://docs.paloaltonetworks.com/enterprise-dlp/enterprise-dlp-admin/configure-enterprise-dlp/email-dlp/how-does-email-dlp-work) as an additional vector of Enterprise DLP. To prevent sensitive data exfiltration, Enterprise Data Loss Prevention (E-DLP) performs inline inspection of all outbound emails. Email DLP then inspects outbound emails and sends the emails to Enterprise DLP for inspection and verdict rendering.


    Depending on your instance location, the endpoint URL can change. The Email DLP endpoint is region specific.


    | Region   | Endpoint                                                  |

    | --------| ------------------    |

    | US       | https://api.us-west1.email.dlp.paloaltonetworks.com       |

    | Europe   | https://api.europe-west3.email.dlp.paloaltonetworks.com   |

    | Asia   | https://api.asia-southeast1.email.dlp.paloaltonetworks.com  |

    | Japan | https://api.asia-northeast1.email.dlp.paloaltonetworks.com/v1 |

    | Europe | https://api.europe-west2.email.dlp.paloaltonetworks.com/v1 |

    | Australia | https://api.australia-southeast1.email.dlp.paloaltonetworks.com/v1 |

    '
  license:
    name: MIT
    url: https://opensource.org/license/mit
  termsOfService: https://www.paloaltonetworks.com/content/dam/pan/en_US/assets/pdf/legal/palo-alto-networks-end-user-license-agreement-eula.pdf
  title: Email DLP Email DLP API API
  version: 1.0.0
servers:
- url: https://api.us-west1.email.dlp.paloaltonetworks.com
tags:
- name: Email DLP API
paths:
  /incident/api/v1/incidents:
    get:
      description: "Retrieves information about [Email DLP](https://docs.paloaltonetworks.com/enterprise-dlp/enterprise-dlp-admin/configure-enterprise-dlp/email-dlp) incidents. \n\nYou can combine the query parameters to drill down on your Email DLP incidents and limit your response sizes. For example:\n\n```curl https://api.us-west1.email.dlp.paloaltonetworks.com/incident/api/v1/incidents?limit=10&from=2023-10-17T02:29:04.402Z&to=2023-11-20T21:44:07.611Z&app_type=exchange-email,gmail-email```\n\n```curl https://api.us-west1.email.dlp.paloaltonetworks.com/incident/api/v1/incidents?to=2023-11-20T19:44:04.395Z&from=2023-10-17T02:29:04.402Z&statuses=resolved,open&severities=very_low&limit=10```\n\nUsing the limit query, the response contains a `next-batch` field that you can use to obtain the next page of results. The response will contain the next endpoint based on the delta:\n\n```\"nextLink\": \"incident/api/incidents/delta?limit=100&from=2021-05-21T01:02:56Z&to=2021-05-22T01:02:56Z\"```\n\nThe report ID field in the response can be used to further inspect the incident with the [Get DLP Report API](/email-dlp/api/get-report-api-v-1-reports-reportid/).\n"
      operationId: get-incident-api-v1-incidents
      parameters:
      - description: Pagination support for the API, this enables you to limit the response size.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: Indicates the beginning of a time-controlled filter.
        in: query
        name: from
        required: false
        schema:
          example: 2023-10-17 02:29:04.402000+00:00
          format: date-time
          type: string
      - description: Indicates the end of a time-controlled filter.
        in: query
        name: to
        required: false
        schema:
          example: 2023-11-20 21:44:07.611000+00:00
          format: date-time
          type: string
      - description: An automatically generated field based on batched results from a previous request.
        in: query
        name: previous_incident_id
        required: false
        schema:
          type: string
      - description: Etiher a single sender or list of senders indicating where the emails came from.
        in: query
        name: senders
        required: false
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - description: Either a single status or a list of statuses to filter on for the Email DLP reports which can be either closed, resolved, under review, or open.
        in: query
        name: statuses
        required: false
        schema:
          items:
            enum:
            - closed
            - resolved
            - under_review
            - open
            type: string
          type: array
          uniqueItems: true
      - description: The list of severity for the shown Email DLP Reports.
        in: query
        name: severities
        required: false
        schema:
          items:
            enum:
            - very_low
            - low
            - medium
            - high
            - critical
            type: string
          type: array
          uniqueItems: true
      - description: The Email DLP policy names that triggered the report.
        in: query
        name: policy_names
        required: false
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - description: An automatically generated ID for the messages.
        in: query
        name: message_ids
        required: false
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - description: The email provider.
        in: query
        name: app_type
        required: false
        schema:
          items:
            enum:
            - exchange-email
            - gmail-email
            type: string
          type: array
          uniqueItems: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIncidentsResponse'
          description: Ok
        '400':
          description: Invalid Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Get Email Incident Details
      tags:
      - Email DLP API
  /incident/api/v1/incidents/{incidentId}/status:
    patch:
      description: You can send a PATCH request to the API to update the status of an Email DLP incident.
      operationId: patch-incident-api-v1-incidents-incidentid-status
      parameters:
      - in: path
        name: incidentId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIncidentStatusRequest'
        required: true
      responses:
        '200':
          description: Ok
        '400':
          description: Invalid Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Update Incident Status
      tags:
      - Email DLP API
  /report/api/v1/reports/{reportId}:
    get:
      description: Retrieves a Data Loss Prevention (DLP) report based on the provided report ID.
      operationId: get-report-api-v1-reports-reportid
      parameters:
      - description: The unique identifier of the DLP report to retrieve.
        in: path
        name: reportId
        required: true
        schema:
          type: string
      - description: Indicates whether to fetch and include snippets in the response.
        in: query
        name: fetchSnippets
        required: false
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReportResponse'
          description: Ok
        '400':
          description: Invalid Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Get DLP report
      tags:
      - Email DLP API
components:
  schemas:
    ScanResult:
      properties:
        action:
          description: The action taken based on the scan result.
          type: string
        dataProfileMatched:
          description: Indicates whether a data profile was matched.
          type: boolean
        data_pattern_rule_1:
          $ref: '#/components/schemas/DataPatternRule'
          description: The first data pattern rule applied.
        data_pattern_rule_2:
          $ref: '#/components/schemas/DataPatternRule'
          description: The second data pattern rule applied.
        data_profile_id:
          description: The ID of the matched data profile.
          type: string
        data_profile_name:
          description: The name of the matched data profile.
          type: string
        data_profile_verdict:
          description: The verdict of the data profile match.
          type: string
        data_profile_version:
          description: The version of the matched data profile.
          format: int32
          type: integer
        report_id:
          description: The ID of the generated report.
          type: string
      type: object
    DataPatternResult:
      properties:
        data_pattern_id:
          description: The ID of the data pattern.
          type: string
        detection_frequency:
          description: The overall frequency of detections.
          format: int32
          type: integer
        detections:
          default: []
          description: An array of detections found.
          items:
            $ref: '#/components/schemas/Detections'
          type: array
        edm_columns:
          description: An array of EDM (Exact Data Match) columns.
          items:
            type: string
          type: array
        empty:
          description: Indicates whether the result is empty.
          type: boolean
        high_confidence_frequency:
          description: The frequency of high confidence detections.
          format: int32
          type: integer
        language:
          description: The language of the detected content.
          type: string
        low_confidence_frequency:
          description: The frequency of low confidence detections.
          format: int32
          type: integer
        medium_confidence_frequency:
          description: The frequency of medium confidence detections.
          format: int32
          type: integer
        name:
          description: The name of the data pattern.
          type: string
        proximity_detection_frequency:
          description: The frequency of proximity detections.
          format: int32
          type: integer
        score:
          description: The score of the data pattern result.
          format: double
          type: number
        state:
          description: The state of the data pattern result.
          type: string
        strict_detection_frequency:
          description: The frequency of strict detections.
          format: int32
          type: integer
        technique:
          description: The technique used for detection.
          type: string
        type:
          description: The type of the data pattern.
          type: string
        unique_checksum_detection_frequency:
          description: The frequency of unique checksum detections.
          format: int32
          type: integer
        unique_detection_frequency:
          description: The overall frequency of unique detections.
          format: int32
          type: integer
        unique_high_confidence_frequency:
          description: The frequency of unique high confidence detections.
          format: int32
          type: integer
        unique_low_confidence_frequency:
          description: The frequency of unique low confidence detections.
          format: int32
          type: integer
        unique_medium_confidence_frequency:
          description: The frequency of unique medium confidence detections.
          format: int32
          type: integer
        unique_proximity_detection_frequency:
          description: The frequency of unique proximity detections.
          format: int32
          type: integer
        unique_strict_detection_frequency:
          description: The frequency of unique strict detections.
          format: int32
          type: integer
        version:
          description: The version of the data pattern.
          format: int32
          type: integer
        weighted_frequency:
          description: The weighted frequency of detections.
          format: int32
          type: integer
      type: object
    Snippet:
      properties:
        high_confidence_detections:
          description: An array of high confidence detections.
          items:
            $ref: '#/components/schemas/DetectionEntry'
          type: array
        low_confidence_detections:
          description: An array of low confidence detections.
          items:
            $ref: '#/components/schemas/DetectionEntry'
          type: array
        matched_confidence_level:
          description: The confidence level of the match.
          type: string
        medium_confidence_detections:
          description: An array of medium confidence detections.
          items:
            $ref: '#/components/schemas/DetectionEntry'
          type: array
        version:
          description: The version of the snippet.
          format: int32
          type: integer
      type: object
    DetectionMetadata:
      properties:
        key:
          description: The key of the metadata.
          type: string
        name:
          description: The name of the metadata.
          type: string
      type: object
    GetIncidentsResponse:
      properties:
        limit:
          description: Specificies the batch limit for the requested result set. The minimum is 1, The maximum, is 1000, and the default is 20 incidents.
          example: 10
          format: int32
          type: integer
        nextLink:
          description: The link you can use to fetch the next set of entries when using a filter in the GET request.
          example: /incident/api/v1/incidents?to=2022-12-03T12:15:30Z&from=2022-12-03T10:15:30Z&app_type=exchange-email&previous_incident_id=2&limit=10
          type: string
        resources:
          items:
            $ref: '#/components/schemas/IncidentResource'
          type: array
      type: object
    DataPatternRule:
      properties:
        data_pattern_results:
          description: An array of results from applying the data pattern rule.
          items:
            $ref: '#/components/schemas/DataPatternResult'
          type: array
      type: object
    UpdateIncidentStatusRequest:
      properties:
        value:
          description: Inidicates the current status of the Email DLP incident, this can indicate whether the incident is open, under review, resovled, or closed.
          enum:
          - closed
          - resolved
          - under_review
          - open
          type: string
      type: object
    DetectionEntry:
      properties:
        detection:
          description: The detected content.
          type: string
        detection_metadata:
          description: An array of metadata associated with the detection.
          items:
            $ref: '#/components/schemas/Metadata'
          type: array
        left:
          description: The context to the left of the detected content.
          type: string
        origOffSet:
          description: The offset of the detection in the original text.
          format: int32
          type: integer
        right:
          description: The context to the right of the detected content.
          type: string
        textLength:
          description: The length of the detected text.
          format: int32
          type: integer
      type: object
    Metadata:
      properties:
        key:
          description: The key of the metadata.
          type: string
        name:
          description: The name of the metadata.
          type: string
      type: object
    GetReportResponse:
      properties:
        dlp_tenant_id:
          description: The DLP-specific tenant ID.
          type: string
        error:
          $ref: '#/components/schemas/Error'
          description: Error information if an error occurred during the scan.
        extracted_file_size_in_bytes:
          description: The size of the extracted file in bytes.
          format: int32
          type: integer
        scan_result:
          description: An array of scan results.
          items:
            $ref: '#/components/schemas/ScanResult'
          type: array
        scan_time:
          description: The timestamp of when the scan was performed.
          format: date-time
          type: string
        snippets:
          additionalProperties:
            $ref: '#/components/schemas/Snippet'
          description: A map of snippets from the scanned content.
          type: object
        tenant_id:
          description: The ID of the tenant associated with the report.
          type: string
        txn_id:
          description: The transaction ID for the report request.
          type: string
      type: object
    Detections:
      properties:
        detection:
          description: The detected content.
          type: string
        detection_metadata:
          description: An array of metadata associated with the detection.
          items:
            $ref: '#/components/schemas/DetectionMetadata'
          type: array
        left:
          description: The context to the left of the detected content.
          type: string
        origOffSet:
          description: The offset of the detection in the original text.
          format: int32
          type: integer
        original_text:
          description: The original text containing the detection.
          type: string
        partition_file_name:
          description: The name of the partition file.
          format: binary
          type: string
        partition_number:
          description: The number of the partition.
          format: int32
          type: integer
        right:
          description: The context to the right of the detected content.
          type: string
        textLength:
          description: The length of the detected text.
          format: int32
          type: integer
      type: object
    Error:
      properties:
        error_code:
          description: The error code associated with the error.
          format: int32
          type: integer
        error_message:
          description: A descriptive message for the error.
          type: string
      type: object
    IncidentResource:
      properties:
        action:
          description: Action taken by Enterprise DLP based on the [Email DLP](https://docs.paloaltonetworks.com/content/techdocs/en_US/enterprise-dlp/enterprise-dlp-admin/configure-enterprise-dlp/email-dlp/add-an-enterprise-dlp-email-policy.html) policy the outbound email matched against.
          enum:
          - monitor
          - fwd_to_manager
          - block
          - fwd_to_admin
          - encrypt
          - quarantine
          type: string
        appType:
          description: The email provider.
          enum:
          - exchange-email
          - gmail-email
          - default-app
          type: string
        assigneeId:
          description: Incident assignee responsible to review and address the Email DLP incident.
          type: string
        createdAt:
          description: Date the Email DLP incident occurred.
          format: date-time
          type: string
        dataProfileId:
          description: 'You can use this field as a pointer to remove duplicate incident entries with the same creation date across batched results. The response automatially includes this field as part of nextLink, if the results span over multiple batches.

            '
          type: string
        incidentId:
          description: An automatically generated ID for the incident.
          type: string
        messageId:
          description: An automtically generated ID for the message.
          type: string
        policyId:
          description: An automtically generated ID for the policy.
          type: string
        policyName:
          description: The name of the [policy](https://docs.paloaltonetworks.com/enterprise-dlp/enterprise-dlp-admin/configure-enterprise-dlp/email-dlp/add-an-enterprise-dlp-email-policy) that triggered the initial report.
          type: string
        receivers:
          description: a list of the persons or entities that recieved the email.
          items:
            type: string
          type: array
        reportId:
          description: The report ID.
          type: string
        sender:
          description: The sender of the email.
          type: string
        sentDate:
          description: The date an email was sent.
          format: date-time
          type: string
        severity:
          description: Severity of the DLP incident specified in the [Email DLP policy](https://docs.paloaltonetworks.com/content/techdocs/en_US/enterprise-dlp/enterprise-dlp-admin/configure-enterprise-dlp/email-dlp/add-an-enterprise-dlp-email-policy.html).
          enum:
          - very_low
          - low
          - medium
          - high
          - critical
          type: string
        status:
          description: The status of the incident.
          enum:
          - closed
          - resolved
          - under_review
          - open
          type: string
        subject:
          description: The subject of the email.
          type: string
        updatedAt:
          description: Date the Email DLP incident status or assignee was updated.
          format: date-time
          type: string
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http