Palo Alto Networks Endpoints API

openapi: 3.2.0
info:
  title: Palo Alto Networks Endpoints API
  version: '1.0'
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
  description: 'Operations tagged Endpoints across 3 of this provider''s published API definitions: palo-alto-cortex-xdr-api-openapi-original.yml, palo-alto-cortex-xsiam-api-openapi-original.yml, palo-alto-networks-endpoints-api-openapi.yml. Each path carries the servers of the definition it was published in.'
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
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
tags:
- name: Endpoints
  description: Endpoint management, isolation, and scanning.
paths:
  /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:
                        - example-ip_item
                        - example-ip_item
                        users:
                        - 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:
                        - Production Gateway 60
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - xdrAuth: []
    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
  /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
      security:
      - xdrAuth: []
    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
  /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
      security:
      - xdrAuth: []
    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
  /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
      security:
      - xdrAuth: []
    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
components:
  responses:
    BadRequest:
      description: Malformed request body or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authentication headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        reply:
          type: object
          properties:
            err_code:
              type: integer
              example: 782
            err_msg:
              type: string
              example: example-err_msg
            err_extra:
              type: string
              example: example-err_extra
          example:
            err_code: 270
            err_msg: example-err_msg
            err_extra: example-err_extra
    Filter:
      type: object
      description: A filter criterion for querying XDR resources.
      required:
      - field
      - operator
      - value
      properties:
        field:
          type: string
          description: Field name to filter on (e.g., incident_id, status, severity).
          example: example-field
        operator:
          type: string
          enum:
          - in
          - contains
          - gte
          - lte
          - eq
          - neq
          description: Comparison operator.
          example: lte
        value:
          description: Filter value. Use an array for the "in" operator, a string or integer for others.
          oneOf:
          - type: string
          - type: integer
          - type: array
            items:
              oneOf:
              - type: string
              - type: integer
          example: example-value
    Endpoint:
      type: object
      description: An endpoint enrolled in Cortex XDR protection.
      properties:
        endpoint_id:
          type: string
          description: Unique endpoint identifier.
          example: '472938'
        endpoint_name:
          type: string
          description: Endpoint hostname.
          example: Branch Sensor 33
        endpoint_type:
          type: string
          enum:
          - SERVER
          - WORKSTATION
          - LAPTOP
          example: WORKSTATION
        endpoint_status:
          type: string
          enum:
          - CONNECTED
          - DISCONNECTED
          - LOST
          - UNINSTALLED
          example: UNINSTALLED
        os_type:
          type: string
          enum:
          - AGENT_OS_WINDOWS
          - AGENT_OS_LINUX
          - AGENT_OS_MAC
          example: AGENT_OS_LINUX
        ip:
          type: array
          items:
            type: string
          description: IP addresses assigned to the endpoint.
          example:
          - example-ip_item
          - example-ip_item
        users:
          type: array
          items:
            type: string
          description: Users logged into the endpoint.
          example:
          - example-users_item
        domain:
          type: string
          example: api.example.com
        alias:
          type: string
          example: example-alias
        first_seen:
          type: integer
          description: First connection timestamp as Unix epoch milliseconds.
          example: 568
        last_seen:
          type: integer
          description: Last connection timestamp as Unix epoch milliseconds.
          example: 191
        content_version:
          type: string
          description: Cortex XDR agent content version.
          example: 6.3.8
        installation_package:
          type: string
          example: example-installation_package
        active_directory:
          type: string
          example: example-active_directory
        install_date:
          type: integer
          example: 551
        endpoint_version:
          type: string
          description: Cortex XDR agent version.
          example: 4.5.5
        is_isolated:
          type: string
          enum:
          - AGENT_ISOLATED
          - AGENT_UNISOLATED
          - PENDING_ISOLATION
          - PENDING_UNISOLATION
          example: PENDING_ISOLATION
        isolation_reason:
          type: string
          example: example-isolation_reason
        scan_status:
          type: string
          enum:
          - SCAN_STATUS_NONE
          - SCAN_STATUS_PENDING
          - SCAN_STATUS_IN_PROGRESS
          - SCAN_STATUS_DONE
          - SCAN_STATUS_FAILED
          - SCAN_STATUS_CANCELLED
          example: SCAN_STATUS_PENDING
        group_name:
          type: array
          items:
            type: string
          example:
          - Production Gateway 60
    SortOrder:
      type: object
      description: Sorting specification for result sets.
      properties:
        field:
          type: string
          description: Field to sort by.
          example: example-field
        keyword:
          type: string
          enum:
          - asc
          - desc
          description: Sort direction.
          example: asc
    ErrorResponse_2:
      type: object
      properties:
        reply:
          type: object
          properties:
            err_code:
              type: integer
              example: 140
            err_msg:
              type: string
              example: example-err_msg
            err_extra:
              type: string
              example: example-err_extra
          example:
            err_code: 33
            err_msg: example-err_msg
            err_extra: example-err_extra
    Filter_2:
      type: object
      description: A filter criterion for querying XSIAM resources.
      required:
      - field
      - operator
      - value
      properties:
        field:
          type: string
          description: Field name to filter on.
          example: example-field
        operator:
          type: string
          enum:
          - in
          - contains
          - gte
          - lte
          - eq
          - neq
          example: eq
        value:
          description: Filter value (string, integer, or array for the "in" operator).
          oneOf:
          - type: string
          - type: integer
          - type: array
            items:
              oneOf:
              - type: string
              - type: integer
          example: example-value
    Endpoint_2:
      type: object
      description: An endpoint enrolled in XSIAM protection.
      properties:
        endpoint_id:
          type: string
          example: '305959'
        endpoint_name:
          type: string
          example: Primary Firewall 16
        endpoint_type:
          type: string
          enum:
          - SERVER
          - WORKSTATION
          - LAPTOP
          example: WORKSTATION
        endpoint_status:
          type: string
          enum:
          - CONNECTED
          - DISCONNECTED
          - LOST
          - UNINSTALLED
          example: UNINSTALLED
        os_type:
          type: string
          enum:
          - AGENT_OS_WINDOWS
          - AGENT_OS_LINUX
          - AGENT_OS_MAC
          example: AGENT_OS_LINUX
        ip:
          type: array
          items:
            type: string
          example:
          - example-ip_item
          - example-ip_item
        users:
          type: array
          items:
            type: string
          example:
          - example-users_item
          - example-users_item
        domain:
          type: string
          example: api.acme-systems.org
        first_seen:
          type: integer
          example: 351
        last_seen:
          type: integer
          example: 449
        endpoint_version:
          type: string
          example: 4.6.8
        content_version:
          type: string
          example: 7.3.2
        is_isolated:
          type: string
          enum:
          - AGENT_ISOLATED
          - AGENT_UNISOLATED
          - PENDING_ISOLATION
          - PENDING_UNISOLATION
          example: AGENT_UNISOLATED
        scan_status:
          type: string
          example: running
    SortOrder_2:
      type: object
      description: Sorting specification for result sets.
      properties:
        field:
          type: string
          example: example-field
        keyword:
          type: string
          enum:
          - asc
          - desc
          example: desc
  securitySchemes:
    xdrAuth:
      type: apiKey
      in: header
      name: x-xdr-hmac-v2
      description: 'Cortex XDR uses a custom HMAC-SHA256 authentication scheme. Each request requires four headers: x-xdr-auth-id (API key ID), x-xdr-nonce (64-character random string), x-xdr-timestamp (Unix epoch milliseconds), and x-xdr-hmac-v2 (SHA-256 hash of apikey + nonce + timestamp). Generate API keys from Cortex XDR Settings > Configurations > API Keys.'
    xsiamAuth:
      type: apiKey
      in: header
      name: x-xdr-hmac-v2
      description: 'Cortex XSIAM uses a custom HMAC-SHA256 authentication scheme. Include four headers on each request: x-xdr-auth-id (API key ID number), x-xdr-nonce (64-character random string), x-xdr-timestamp (Unix epoch milliseconds as a string), and x-xdr-hmac-v2 (SHA-256 hash of api_key + nonce + timestamp). Standard and Advanced API key types are supported; Advanced keys provide additional security through IP allowlisting. Generate API keys from XSIAM Settings > Configurations > API Keys.'
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.
x-refined-from:
- palo-alto-cortex-xdr-api-openapi-original.yml
- palo-alto-cortex-xsiam-api-openapi-original.yml
- palo-alto-networks-endpoints-api-openapi.yml