openapi: 3.2.0
info:
  contact: {}
  description: "Beta Incidents API providing advanced incident management features including paginated retrieval, \ncomprehensive filtering and sorting, batch incident updates, and signed URL generation for secure \nincident data downloads. These endpoints offer enhanced functionality for large-scale incident analysis.\n"
  license:
    name: MIT
    url: https://opensource.org/license/mit
  title: Incidents API (Beta) Incidents API (Beta) API
  version: 1.0.0
servers:
- url: https://api.dlp.paloaltonetworks.com
tags:
- name: Incidents API (Beta)
paths:
  /v4/api/incidents:
    get:
      description: "Retrieve a paginated list of DLP incidents with optional filtering and sorting capabilities. \nThis endpoint provides efficient access to large incident datasets through token-based pagination.\n"
      operationId: get-v4-api-incidents
      parameters:
      - description: The pagination token received from the initial POST /incidents API call. This token identifies the specific query for which results are being paginated.
        in: query
        name: token
        required: true
        schema:
          type: string
      - description: The row offset from which to start fetching incident records. For the first paginated request, this would typically be page_size. For subsequent requests, it would be previous_offset + page_size
        in: query
        name: offset
        required: true
        schema:
          type: string
      - description: The maximum number of incident records to return in this paginated response. This value should be between 1 and 1000
        in: query
        name: pageSize
        required: true
        schema:
          type: string
      - description: Optional flag to include data profile information in the response.
        in: query
        name: include_data_profiles
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                query_token: test_token
                rows:
                - action: block
                  asset_name: test asset name
                  control_point: PRISMA_ACCESS
                  created_date: 1753121720515000
                  data_profile_id: '11995064'
                  destination: web-browsing
                  incident_id: 58feac56-e49d-43b3-ade3-c2d8e34ecd68
                  modified_date: 1753121720515739
                  policy_type: Network
                  report_id: '3082846756'
                  severity: '2'
                  source: palodlp11
                  source_region: US_STG
                  status: New
                  sub_policy_type: Data in Motion
                  url_domain: test url domain
                status: READY
                status_description: Query results are ready.
                total_rows: 1
              schema:
                $ref: '#/components/schemas/IncidentInventoryResponse'
          description: Successful!
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Retrieve Paginated DLP Incidents
      tags:
      - Incidents API (Beta)
    post:
      description: "Query the DLP incident inventory with customizable parameters for comprehensive incident analysis. \nSubmit a POST request with filter criteria to retrieve matching incidents with advanced filtering and sorting.\n"
      operationId: post-v4-api-incidents
      parameters:
      - description: Optional flag to include data profile information in the response.
        in: query
        name: include_data_profiles
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              time_range: HOUR_24
            schema:
              $ref: '#/components/schemas/IncidentInventoryRequest'
        description: Request body containing filter criteria, time range, pagination parameters, and sorting options for incident inventory queries.
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                query_token: test_token
                rows:
                - action: block
                  asset_name: test asset name
                  control_point: PRISMA_ACCESS
                  created_date: 1753121720515000
                  data_profile_id: '11995064'
                  destination: web-browsing
                  incident_id: 58feac56-e49d-43b3-ade3-c2d8e34ecd68
                  modified_date: 1753121720515739
                  policy_type: Network
                  report_id: '3082846756'
                  severity: '2'
                  source: palodlp11
                  source_region: US_STG
                  status: New
                  sub_policy_type: Data in Motion
                  url_domain: test url domain
                status: READY
                status_description: Query results are ready.
                total_rows: 1
              schema:
                $ref: '#/components/schemas/IncidentInventoryResponse'
          description: Successful!
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Query DLP Incident Inventory
      tags:
      - Incidents API (Beta)
  /v4/api/incidents/download:
    post:
      description: "Generate a signed URL for downloading DLP incident data based on specified criteria. The signed URL \ncan be used to securely download incident information for external processing or archival. The URL is \nvalid for a limited time period.\n"
      operationId: post-v4-api-incidents-download
      requestBody:
        content:
          application/json:
            example:
              time_range: HOUR_24
            schema:
              $ref: '#/components/schemas/ResultsDownloadRequest'
        description: Request body containing filter criteria and download parameters for generating the signed URL.
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                download_url: https://storage.googleapis.com/casb-data-platform-prod-uim-inc-export/1494634703/incidents_20250721_205140_e3f288124dec432c8f94ed4f5b49b19b.csv.gz?test_signed_url
              schema:
                $ref: '#/components/schemas/ResultsDownloadResponse'
          description: Successful!
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Generate Signed URL for Incident Download
      tags:
      - Incidents API (Beta)
  /v4/api/incidents/management:
    post:
      description: "Update incident properties including status, assignees, notes, and priority for comprehensive incident \nlifecycle management. This endpoint allows batch updates to multiple incidents simultaneously, improving \noperational efficiency.\n"
      operationId: post-v4-api-incidents-management
      requestBody:
        content:
          application/json:
            example:
              incident_ids:
              - 5ba587fd-4b83-416d-998f-16d79c7da889
              - 58feac56-e49d-43b3-ade3-c2d8e34ecd68
              update_details:
                assignee_display_name: John Doe
                assignee_email: john.doe@example.com
                assignee_id: user123
                notes: Escalated for further investigation
                priority: 2
                resolution_status: under_investigation
                resolved_by: admin@example.com
                tag: security-review
            schema:
              $ref: '#/components/schemas/IncidentUpdateRequest'
        description: Request body containing incident IDs and the update details to apply to those incidents.
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                success: 1
              schema:
                $ref: '#/components/schemas/IncidentUpdateResults'
          description: Successful!
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Update Incident Management Properties
      tags:
      - Incidents API (Beta)
  /v4/api/incidents/{id}:
    get:
      description: "Retrieve comprehensive details for a specific DLP incident using its unique identifier. This endpoint \nprovides complete incident information including all metadata and detection details.\n"
      operationId: get-v4-api-incidents-id
      parameters:
      - description: The unique identifier of the incident to retrieve.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                rows:
                - action: block
                  app_id: '109'
                  app_instance_id: test
                  app_name: test
                  app_tags:
                  - test1
                  - test2
                  app_type: '0'
                  asset_hash: test hash
                  asset_id: 5ba587fd-4b83-416d-998f-16d79c7da889
                  asset_name: UNKNOWN
                  asset_risk: 25
                  asset_size: test
                  assigned_to: test
                  assignee_email: test
                  assignee_name: test
                  category: test
                  control_point: NGFW
                  created_date: 1752910252943000
                  data_patterns:
                  - category_score: 0
                    detection_frequency: 4
                    high_confidence_frequency: 2
                    id: 65779c793375232371f9886c
                    language: test
                    low_confidence_frequency: 4
                    medium_confidence_frequency: 0
                    name: test
                    strict_detection_frequency: 0
                    sub_category_score: 0
                    technique: regex
                    total_detection_frequency: 4
                    total_strict_detection_frequency: 0
                    type: predefined
                    version: 1
                    weighted_frequency: 0
                  data_profiles:
                  - id: '11995181'
                    name: AEL_Granular
                    version: test
                  destination: 185.125.188.57
                  device_info:
                  - id: test
                    ip: 188.188.188.10
                    loggedin_users:
                    - test
                    name: test
                    serial_number: 024401003837
                  direction: upload
                  endpoint_os_info:
                    dlp_client_version: test
                    gp_version: test
                    os_type: test
                    os_version: test
                  exception_rule_results:
                  - action: allow
                    data_profile_id: '11995181'
                    destination_app: Slack
                    destination_url: https://slack.com
                    id: rule-12345
                    log_severity: medium
                    source_group: Engineering
                    source_user: john.doe@example.com
                    version: 1
                  exposure: test
                  exposure_details:
                    cloud_url: test cloud url
                    is_exposed_by_parent_folder: false
                    is_public_url: false
                    is_shared_url: false
                    is_sign_in_required: true
                    public_url: test public url
                  id: 5ba587fd-4b83-416d-998f-16d79c7da889
                  modified_date: 1753137046114000
                  notes: test
                  peripheral_info:
                    group_id: ''
                    group_name: ''
                    id: test id
                    is_known: false
                    manufacturer_name: General
                    name: USB-4GB
                    product_id: '1000'
                    product_name: USB Flash Disk
                    serial_number: 0415090000013290
                    type: usb
                    vendor_id: 090C
                  policy:
                    policy_id: test
                    policy_type: network
                    policy_version: test
                  priority: 1
                  reason_for_action: test
                  report_date: 1752910252937000
                  report_id: '229650498'
                  resolved_by: test
                  severity: '5'
                  source: 188.188.188.10
                  status: New
                  tag: test
                  tsg_id: '1016831479'
                  url: test
                  user_department: test
                  user_email: test
                  user_id: globaltestuser1
                  user_location: test
                  user_manager: test
                  user_name: test
                status: READY
                status_description: Query results are ready.
                total_rows: 1
              schema:
                $ref: '#/components/schemas/IncidentDetailResponse'
          description: Successful!
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      security:
      - Bearer: []
      summary: Retrieve Incident Details by ID
      tags:
      - Incidents API (Beta)
components:
  schemas:
    DataPattern:
      properties:
        category_score:
          format: int32
          type: integer
        detection_frequency:
          format: int32
          type: integer
        high_confidence_frequency:
          format: int32
          type: integer
        id:
          type: string
        language:
          type: string
        low_confidence_frequency:
          format: int32
          type: integer
        medium_confidence_frequency:
          format: int32
          type: integer
        name:
          type: string
        strict_detection_frequency:
          format: int32
          type: integer
        sub_category_score:
          format: int32
          type: integer
        technique:
          type: string
        total_detection_frequency:
          format: int32
          type: integer
        total_strict_detection_frequency:
          format: int32
          type: integer
        type:
          type: string
        version:
          format: int32
          type: integer
        weighted_frequency:
          format: int32
          type: integer
      type: object
    PeripheralInfo:
      properties:
        group_id:
          type: string
        group_name:
          type: string
        id:
          type: string
        is_known:
          type: boolean
        manufacturer_name:
          type: string
        name:
          type: string
        product_id:
          type: string
        product_name:
          type: string
        serial_number:
          type: string
        type:
          type: string
        vendor_id:
          type: string
      type: object
    Policy:
      properties:
        policy_id:
          type: string
        policy_type:
          type: string
        policy_version:
          type: string
      type: object
    DeviceInfo:
      properties:
        id:
          type: string
        ip:
          type: string
        loggedin_users:
          items:
            type: string
          type: array
        name:
          type: string
        serial_number:
          type: string
      type: object
    ExceptionRuleEntity:
      properties:
        action:
          type: string
        data_profile_id:
          type: string
        destination_app:
          type: string
        destination_url:
          type: string
        id:
          type: string
        log_severity:
          type: string
        source_group:
          type: string
        source_user:
          type: string
        version:
          format: int64
          type: integer
      type: object
    ExposureDetails:
      properties:
        cloud_url:
          type: string
        is_exposed_by_parent_folder:
          type: boolean
        is_public_url:
          type: boolean
        is_shared_url:
          type: boolean
        is_sign_in_required:
          type: boolean
        public_url:
          type: string
      type: object
    IncidentUpdateDetails:
      properties:
        assignee_display_name:
          type: string
        assignee_email:
          type: string
        assignee_id:
          type: string
        notes:
          type: string
        priority:
          format: int32
          type: integer
        resolution_status:
          type: string
        resolved_by:
          type: string
        tag:
          type: string
      type: object
    IncidentDetailResponse:
      properties:
        query_token:
          type: string
        rows:
          items:
            $ref: '#/components/schemas/IncidentDetailEntity'
          type: array
        status:
          enum:
          - READY
          - PENDING
          type: string
        status_description:
          type: string
      type: object
    IncidentInventoryResponse:
      properties:
        query_token:
          type: string
        rows:
          items:
            $ref: '#/components/schemas/IncidentInventoryEntity'
          type: array
        status:
          enum:
          - READY
          - PENDING
          type: string
        status_description:
          type: string
        total_rows:
          format: int64
          type: integer
      type: object
    IncidentUpdateRequest:
      properties:
        incident_ids:
          items:
            format: uuid
            type: string
          minItems: 1
          type: array
        update_details:
          $ref: '#/components/schemas/IncidentUpdateDetails'
      required:
      - incident_ids
      - update_details
      type: object
    IncidentInventoryRequest:
      properties:
        columns:
          description: Optional columns to include in the response
          items:
            type: string
          type: array
          writeOnly: true
        end_time:
          description: Required when time_range is CUSTOM. Start time as Unix timestamp in milliseconds(ms).
          format: int64
          type: integer
          writeOnly: true
        filter:
          description: "Filter expression string\n<br>Operators supported: =, in and AND\n<br>Pattern: {FilterName} = {value} or {FilterName} in ({value1}, {value2}, ...)\n<br>Supported FilterName values:\n- Action: Filter by action taken (e.g., 'block', 'allow')\n- ApplicationName: Filter by application name\n- Asset: Filter by asset name\n- AssigneeId: Filter by assignee user ID\n- AssigneeName: Filter by assignee display name\n- Channel: Filter by channel (e.g., 'PRISMA_ACCESS', 'NGFW')\n- DataPattern: Filter by detection types/data patterns (e.g., 'SSN', 'Credit Card')\n- DataProfile: Filter by data profile ID\n- Destination: Filter by destination\n- IncidentId: Filter by specific incident ID\n- Priority: Filter by priority level (numeric values 1-5)\n- ReportId: Filter by report ID\n- Severity: Filter by severity level\n        - 5 = Critical\n        - 4 = High\n        - 3 = Medium\n        - 2 = Low\n        - 1 = Informational\n- Source: Filter by source\n- Region: Filter by region (e.g., 'US', 'EU', 'UK', 'SG', 'IN', 'AU', 'CA', 'JP')\n- Status: Filter by incident status (e.g., 'New', 'open', 'under_investigation', 'closed')\n- UrlDomain: Filter by URL domain\n- Tag: Filter by incident tags\n\nExamples:\n- \"Tag = 'Needs Escalation'\"\n- \"Status in ('New','open','under_investigation')\"\n- \"UrlDomain = 'dlptest.com'\"\n- \"Channel = 'PRISMA_ACCESS' AND DataProfile in ('11995030','11995033')\"\n"
          example: Tag = 'Needs Escalation'
          minLength: 1
          type: string
        max_rows:
          description: Maximum number of rows to return (optional, e.g., 1000)
          example: 10000
          format: int32
          type: integer
          writeOnly: true
        page_size:
          description: Size for pagination
          format: int32
          type: integer
          writeOnly: true
        sort_by:
          description: Optional field to sort by
          type: string
          writeOnly: true
        sort_order:
          description: Optional sort order (asc/desc)
          type: string
          writeOnly: true
        start_time:
          description: Required when time_range is CUSTOM. Start time as Unix timestamp in milliseconds(ms).
          format: int64
          type: integer
          writeOnly: true
        time_range:
          enum:
          - HOUR_1
          - HOUR_3
          - HOUR_24
          - DAY_7
          - DAY_30
          - DAY_90
          - CUSTOM
          type: string
      required:
      - time_range
      type: object
    ResultsDownloadRequest:
      properties:
        columns:
          description: Optional columns to include in the response
          items:
            type: string
          type: array
          writeOnly: true
        end_time:
          description: Required when time_range is CUSTOM. End time as Unix timestamp in milliseconds(ms).
          format: int64
          type: integer
          writeOnly: true
        filter:
          description: "Filter expression string\n<br>Operators supported: =, in and AND\n<br>Pattern: {FilterName} = {value} or {FilterName} in ({value1}, {value2}, ...)\n<br>Supported FilterName values:\n- Action: Filter by action taken (e.g., 'block', 'allow')\n- ApplicationName: Filter by application name\n- Asset: Filter by asset name\n- AssigneeId: Filter by assignee user ID\n- AssigneeName: Filter by assignee display name\n- Channel: Filter by channel (e.g., 'PRISMA_ACCESS', 'NGFW')\n- DataPattern: Filter by detection types/data patterns (e.g., 'SSN', 'Credit Card')\n- DataProfile: Filter by data profile ID\n- Destination: Filter by destination\n- IncidentId: Filter by specific incident ID\n- Priority: Filter by priority level (numeric values 1-5)\n- ReportId: Filter by report ID\n- Severity: Filter by severity level\n        - 5 = Critical\n        - 4 = High\n        - 3 = Medium\n        - 2 = Low\n        - 1 = Informational\n- Source: Filter by source\n- Region: Filter by region (e.g., 'US', 'EU', 'UK', 'SG', 'IN', 'AU', 'CA', 'JP')\n- Status: Filter by incident status (e.g., 'New', 'open', 'under_investigation', 'closed')\n- UrlDomain: Filter by URL domain\n- Tag: Filter by incident tags\n\nExamples:\n- \"Tag = 'Needs Escalation'\"\n- \"Status in ('New','open','under_investigation')\"\n- \"UrlDomain = 'dlptest.com'\"\n- \"Channel = 'PRISMA_ACCESS' AND DataProfile in ('11995030','11995033')\"\n"
          example: Tag = 'Needs Escalation'
          type: string
        max_rows:
          description: Maximum number of rows to return (optional, e.g., 1000)
          example: 10000
          format: int32
          type: integer
          writeOnly: true
        sort_by:
          description: Optional field to sort by
          type: string
          writeOnly: true
        sort_order:
          description: Optional sort order (asc/desc)
          type: string
          writeOnly: true
        start_time:
          description: Required when time_range is CUSTOM. Start time as Unix timestamp in milliseconds(ms).
          format: int64
          type: integer
          writeOnly: true
        time_range:
          enum:
          - HOUR_1
          - HOUR_3
          - HOUR_24
          - DAY_7
          - DAY_30
          - DAY_90
          - CUSTOM
          type: string
        token:
          type: string
      required:
      - time_range
      type: object
    IncidentDetailEntity:
      properties:
        action:
          type: string
        app_id:
          type: string
        app_instance_id:
          type: string
        app_name:
          type: string
        app_tags:
          items:
            type: string
          type: array
        app_type:
          type: string
        asset_hash:
          type: string
        asset_id:
          type: string
        asset_name:
          type: string
        asset_risk:
          format: double
          type: number
        asset_size:
          type: string
        assigned_to:
          type: string
        assignee_email:
          type: string
        assignee_name:
          type: string
        category:
          type: string
        control_point:
          type: string
        created_date:
          format: int64
          type: integer
        data_patterns:
          items:
            $ref: '#/components/schemas/DataPattern'
          type: array
        data_profiles:
          items:
            $ref: '#/components/schemas/DataProfile'
          type: array
        destination:
          type: string
        device_info:
          items:
            $ref: '#/components/schemas/DeviceInfo'
          type: array
        direction:
          type: string
        endpoint_os_info:
          $ref: '#/components/schemas/EndpointOsInfo'
        exception_rule_results:
          items:
            $ref: '#/components/schemas/ExceptionRuleEntity'
          type: array
        exposure:
          type: string
        exposure_details:
          $ref: '#/components/schemas/ExposureDetails'
        id:
          type: string
        modified_date:
          format: int64
          type: integer
        notes:
          type: string
        peripheral_info:
          $ref: '#/components/schemas/PeripheralInfo'
        policy:
          $ref: '#/components/schemas/Policy'
        priority:
          format: int32
          type: integer
        reason_for_action:
          type: string
        report_date:
          format: int64
          type: integer
        report_id:
          type: string
        resolved_by:
          type: string
        severity:
          type: string
        source:
          type: string
        status:
          type: string
        tag:
          type: string
        tsg_id:
          type: string
        url:
          type: string
        user_department:
          type: string
        user_email:
          type: string
        user_id:
          type: string
        user_location:
          type: string
        user_manager:
          type: string
        user_name:
          type: string
      type: object
    DataProfile:
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: string
      type: object
    IncidentUpdateResults:
      properties:
        error:
          $ref: '#/components/schemas/ErrorInfo'
        success:
          format: int32
          type: integer
      type: object
    IncidentInventoryEntity:
      properties:
        action:
          type: string
        asset_name:
          type: string
        assignee_email:
          type: string
        assignee_id:
          type: string
        assignee_name:
          type: string
        control_point:
          type: string
        created_date:
          format: int64
          type: integer
        data_profile_id:
          type: string
        destination:
          type: string
        incident_id:
          type: string
        modified_date:
          format: int64
          type: integer
        notes:
          type: string
        peripheral_name:
          type: string
        peripheral_type:
          type: string
        policy_type:
          type: string
        priority:
          format: int32
          type: integer
        report_id:
          type: string
        resolved_by:
          type: string
        severity:
          type: string
        source:
          type: string
        source_region:
          type: string
        status:
          type: string
        sub_policy_type:
          type: string
        tag:
          type: string
        url_domain:
          type: string
      type: object
    ResultsDownloadResponse:
      properties:
        download_url:
          type: string
      type: object
    ErrorInfo:
      properties:
        error_code:
          minLength: 1
          type: string
        error_message:
          minLength: 1
          type: string
        id:
          minLength: 1
          type: string
      type: object
    EndpointOsInfo:
      properties:
        dlp_client_version:
          type: string
        gp_version:
          type: string
        os_type:
          type: string
        os_version:
          type: string
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http