Cortex XDR API

openapi: 3.1.0
info:
  title: Palo Alto Networks Cortex XDR REST API
  description: >-
    REST API for the Cortex XDR extended detection and response platform.
    Provides programmatic access to incidents, alerts, endpoints, scripts,
    XQL queries, and audit logs. Cortex XDR correlates data from network,
    endpoint, cloud, and third-party sources to detect and investigate threats.
    Authentication uses a custom HMAC-SHA256 scheme: generate an API key ID
    and secret from the Cortex XDR settings, then sign each request using the
    x-xdr-auth-id, x-xdr-nonce, x-xdr-timestamp, and x-xdr-hmac-v2 headers.
    All API endpoints use POST with JSON request bodies containing a request_data
    object for filters and parameters.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/cortex/docs/xdr/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api-{fqdn}/public_api/v1
  description: Cortex XDR tenant API endpoint.
  variables:
    fqdn:
      description: >-
        Tenant FQDN from the Cortex XDR settings page (e.g.,
        example.xdr.us.paloaltonetworks.com).
      default: example.xdr.us.paloaltonetworks.com
security:
- xdrAuth: []
tags:
- name: Alerts
  description: Alert retrieval and management.
- name: Audit
  description: Audit and management log retrieval.
- name: Endpoints
  description: Endpoint management, isolation, and scanning.
- name: Incidents
  description: Incident management and investigation.
- name: Scripts
  description: Script execution and results retrieval.
- name: XQL
  description: XQL (Extended Query Language) query execution.
paths:
  /incidents/get_incidents:
    post:
      operationId: getIncidents
      summary: Palo Alto Networks List Incidents
      description: >-
        Returns a list of incidents matching the specified filter criteria.
        Incidents group related alerts into a unified investigation context.
        Supports filtering by incident ID, status, severity, and creation time.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                      description: Filter criteria to apply to the incident list.
                    search_from:
                      type: integer
                      description: Pagination offset (zero-based).
                      default: 0
                    search_to:
                      type: integer
                      description: Upper bound of the result range.
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetIncidentsRequestExample:
                summary: Default getIncidents request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Incidents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      incidents:
                        type: array
                        items:
                          $ref: '#/components/schemas/Incident'
              examples:
                GetIncidents200Example:
                  summary: Default getIncidents 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 176
                      result_count: 940
                      incidents:
                      - incident_id: '877543'
                        incident_name: Branch Gateway 82
                        description: Firewall traffic applied alert threat blocked Security rule.
                        status: resolved_threat_handled
                        severity: informational
                        assigned_user_mail: [email protected]
                        assigned_user_pretty_name: Carlos Smith
                        alert_count: 509
                        low_severity_alert_count: 929
                        med_severity_alert_count: 295
                        high_severity_alert_count: 602
                        critical_severity_alert_count: 936
                        user_count: 170
                        host_count: 720
                        creation_time: 1707012665747
                        modification_time: 1744706901976
                        detection_time: 1704757310414
                        starred: true
                        xdr_url: https://portal.acme-systems.org/0455da
                        rule_based_score: 942
                        manual_score: 174
        '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/get_incident_extra_data:
    post:
      operationId: getIncidentExtraData
      summary: Palo Alto Networks Get Incident Details
      description: >-
        Returns detailed information about a specific incident including
        all associated alerts, network artifacts, file artifacts, and
        endpoint details.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - incident_id
                  properties:
                    incident_id:
                      type: string
                      description: Unique identifier of the incident.
                    alerts_limit:
                      type: integer
                      description: Maximum number of alerts to include in response.
                      default: 1000
            examples:
              GetIncidentExtraDataRequestExample:
                summary: Default getIncidentExtraData request
                x-microcks-default: true
                value:
                  request_data:
                    incident_id: '709824'
                    alerts_limit: 1000
      responses:
        '200':
          description: Incident details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      incident:
                        $ref: '#/components/schemas/IncidentDetail'
                      alerts:
                        type: object
                        properties:
                          total_count:
                            type: integer
                          data:
                            type: array
                            items:
                              $ref: '#/components/schemas/Alert'
                      network_artifacts:
                        type: object
                      file_artifacts:
                        type: object
              examples:
                GetIncidentExtraData200Example:
                  summary: Default getIncidentExtraData 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      incident: example-incident
                      alerts:
                        total_count: 428
                        data:
                        - 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.
                      network_artifacts: {}
                      file_artifacts: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incidents/update_incident:
    post:
      operationId: updateIncident
      summary: Palo Alto Networks Update Incident
      description: >-
        Updates the status, severity, assignee, or other mutable fields of a
        specific incident. Only the fields provided in the request body are
        modified.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - incident_id
                  properties:
                    incident_id:
                      type: string
                    status:
                      type: string
                      enum:
                      - new
                      - under_investigation
                      - resolved_threat_handled
                      - resolved_known_issue
                      - resolved_duplicate
                      - resolved_false_positive
                      - resolved_other
                    severity:
                      type: string
                      enum:
                      - high
                      - medium
                      - low
                    assigned_user_mail:
                      type: string
                      description: Email of the user to assign the incident to.
                    assigned_user_pretty_name:
                      type: string
                    resolve_comment:
                      type: string
                      description: Resolution comment (required when closing an incident).
                    add_comment:
                      type: string
                      description: Comment to add to the incident timeline.
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  request_data:
                    incident_id: '498189'
                    status: resolved_duplicate
                    severity: high
                    assigned_user_mail: [email protected]
                    assigned_user_pretty_name: Jane Garcia
                    resolve_comment: Detected endpoint configured policy firewall Security malware rule suspicious alert incident network.
                    add_comment: Endpoint detected suspicious incident network firewall threat malware configured blocked alert investigation.
      responses:
        '200':
          description: Incident updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: boolean
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    reply: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
                        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.
                      - 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
  /endpoints/get_endpoints:
    post:
      operationId: getEndpoints
      summary: Palo Alto Networks List Endpoints
      description: >-
        Returns a list of endpoints enrolled in Cortex XDR. Supports filtering
        by endpoint ID, hostname, IP address, operating system, and protection
        status.
      tags:
      - Endpoints
      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:
              GetEndpointsRequestExample:
                summary: Default getEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Endpoints returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      endpoints:
                        type: array
                        items:
                          $ref: '#/components/schemas/Endpoint'
              examples:
                GetEndpoints200Example:
                  summary: Default getEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 1
                      result_count: 161
                      endpoints:
                      - endpoint_id: '472938'
                        endpoint_name: Branch Sensor 33
                        endpoint_type: WORKSTATION
                        endpoint_status: UNINSTALLED
                        os_type: AGENT_OS_LINUX
                        ip: &id003
                        - example-ip_item
                        - example-ip_item
                        users: &id004
                        - example-users_item
                        domain: api.example.com
                        alias: example-alias
                        first_seen: 568
                        last_seen: 191
                        content_version: 6.3.8
                        installation_package: example-installation_package
                        active_directory: example-active_directory
                        install_date: 551
                        endpoint_version: 4.5.5
                        is_isolated: PENDING_ISOLATION
                        isolation_reason: example-isolation_reason
                        scan_status: SCAN_STATUS_PENDING
                        group_name: &id005
                        - Production Gateway 60
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/isolate:
    post:
      operationId: isolateEndpoints
      summary: Palo Alto Networks Isolate Endpoints
      description: >-
        Isolates one or more endpoints from the network, preventing all
        inbound and outbound communications except to the Cortex XDR service.
        Use endpoint IDs, IP addresses, or hostnames to identify targets.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id:
                      type: string
                      description: Single endpoint ID to isolate.
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                      description: List of endpoint IDs to isolate.
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                      description: Filter to select endpoints for isolation.
            examples:
              IsolateEndpointsRequestExample:
                summary: Default isolateEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id: '873939'
                    endpoint_id_list:
                    - '727469'
                    - '227456'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint isolation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                        description: Action ID to poll for completion status.
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                IsolateEndpoints200Example:
                  summary: Default isolateEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '179327'
                      status: 199
                      endpoints_count: 392
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/unisolate:
    post:
      operationId: unisolateEndpoints
      summary: Palo Alto Networks Unisolate Endpoints
      description: >-
        Removes network isolation from one or more endpoints, restoring full
        network connectivity. Use this endpoint after an investigation is
        complete and the threat has been remediated.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id:
                      type: string
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
            examples:
              UnisolateEndpointsRequestExample:
                summary: Default unisolateEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id: '692398'
                    endpoint_id_list:
                    - '178680'
                    - '543834'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint unisolation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                UnisolateEndpoints200Example:
                  summary: Default unisolateEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '168979'
                      status: 596
                      endpoints_count: 930
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /endpoints/scan:
    post:
      operationId: scanEndpoints
      summary: Palo Alto Networks Scan Endpoints
      description: >-
        Initiates a malware scan on one or more endpoints. The scan runs the
        Cortex XDR agent's local analysis engine to detect and quarantine
        malicious files.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  properties:
                    endpoint_id_list:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
            examples:
              ScanEndpointsRequestExample:
                summary: Default scanEndpoints request
                x-microcks-default: true
                value:
                  request_data:
                    endpoint_id_list:
                    - '586813'
                    - '318804'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
      responses:
        '200':
          description: Endpoint scan initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      action_id:
                        type: string
                      status:
                        type: integer
                      endpoints_count:
                        type: integer
              examples:
                ScanEndpoints200Example:
                  summary: Default scanEndpoints 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      action_id: '902089'
                      status: 779
                      endpoints_count: 286
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scripts/run_script:
    post:
      operationId: runScript
      summary: Palo Alto Networks Execute Script on Endpoints
      description: >-
        Executes a script from the script library on one or more endpoints.
        Scripts can perform remediation actions, collect forensic data, or
        run custom commands. Returns an action ID for polling execution status.
      tags:
      - Scripts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - script_uid
                  properties:
                    script_uid:
                      type: string
                      description: Unique identifier of the script from the script library.
                    endpoint_ids:
                      type: array
                      items:
                        type: string
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    parameters_values:
                      type: object
                      description: Script parameter key-value pairs.
                      additionalProperties: true
                    timeout:
                      type: integer
                      description: Script execution timeout in seconds.
                      default: 600
            examples:
              RunScriptRequestExample:
                summary: Default runScript request
                x-microcks-default: true
                value:
                  request_data:
                    script_uid: '595817'
                    endpoint_ids:
                    - '221362'
                    - '707960'
                    filters:
                    - field: example-field
                      operator: lte
                      value: example-value
                    - field: example-field
                      operator: lte
                      value: example-value
                    parameters_values: {}
                    timeout: 600
      responses:
        '200':
          description

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-cortex-xdr-api-openapi-original.yml