Cortex XSIAM API

openapi: 3.1.0
info:
  title: Palo Alto Networks Cortex XSIAM REST API
  description: >-
    REST API for the Cortex XSIAM (Extended Security Intelligence and Automation
    Management) AI-driven security operations platform. Provides programmatic
    access to incidents, alerts, endpoints, XQL queries, assets, audit logs,
    and data source ingestion. XSIAM extends Cortex XDR with a full SOC platform
    including SIEM, SOAR, and threat intelligence capabilities. Authentication
    uses a custom HMAC-SHA256 scheme: generate an API key ID and secret from the
    XSIAM settings, then include x-xdr-auth-id, x-xdr-nonce, x-xdr-timestamp,
    and x-xdr-hmac-v2 headers on every request. All endpoints use POST with JSON
    request bodies.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/cortex/docs/xsiam/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api-{fqdn}/public_api/v1
  description: Cortex XSIAM tenant API endpoint.
  variables:
    fqdn:
      description: >-
        Tenant FQDN from the XSIAM settings page (e.g.,
        example.xsiam.paloaltonetworks.com).
      default: example.xsiam.paloaltonetworks.com
security:
- xsiamAuth: []
tags:
- name: Alerts
  description: Alert retrieval and filtering.
- name: Assets
  description: Asset inventory management.
- name: Audit
  description: Audit and management log retrieval.
- name: Endpoints
  description: Endpoint inventory management.
- name: Incidents
  description: Incident retrieval and management.
- name: Ingestion
  description: Data source configuration for log ingestion.
- name: XQL
  description: XQL query execution against the XSIAM data lake.
paths:
  /incidents/get_incidents:
    post:
      operationId: getIncidents
      summary: Palo Alto Networks List Incidents
      description: >-
        Returns a list of incidents matching the specified filter criteria.
        XSIAM incidents correlate alerts from endpoint, network, cloud, and
        SIEM data sources using AI-powered analytics. Supports filtering by
        status, severity, and time range.
      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 for incident list.
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      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: eq
                      value: example-value
                    - field: example-field
                      operator: eq
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: desc
      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: 193
                      result_count: 967
                      incidents:
                      - incident_id: '930948'
                        incident_name: Staging Gateway 69
                        description: Malware endpoint configured on threat detected violation blocked rule violation suspicious.
                        status: resolved_false_positive
                        severity: medium
                        assigned_user_mail: [email protected]
                        assigned_user_pretty_name: Carlos Smith
                        alert_count: 102
                        creation_time: 1747691175363
                        modification_time: 1703382684754
                        detection_time: 1724626599746
                        starred: true
                        xdr_url: https://vpn.test-corp.net/d6af6d
                        mitre_tactics_ids_and_names: &id001
                        - '100279'
                        - '498972'
                        mitre_techniques_ids_and_names: &id002
                        - '186119'
                        - '416278'
                      - incident_id: '930948'
                        incident_name: Staging Gateway 69
                        description: Malware endpoint configured on threat detected violation blocked rule violation suspicious.
                        status: resolved_false_positive
                        severity: medium
                        assigned_user_mail: [email protected]
                        assigned_user_pretty_name: Carlos Smith
                        alert_count: 102
                        creation_time: 1747691175363
                        modification_time: 1703382684754
                        detection_time: 1724626599746
                        starred: true
                        xdr_url: https://vpn.test-corp.net/d6af6d
                        mitre_tactics_ids_and_names: *id001
                        mitre_techniques_ids_and_names: *id002
        '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
  /alerts/get_alerts:
    post:
      operationId: getAlerts
      summary: Palo Alto Networks Get Alerts
      description: >-
        Returns alerts matching the specified filter criteria. XSIAM ingests
        and normalizes alerts from endpoint agents, network sensors, cloud
        providers, and third-party SIEM sources. Supports filtering by alert
        category, severity, source, and time range.
      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: eq
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: desc
      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: 527
                      result_count: 162
                      alerts:
                      - alert_id: '590285'
                        detection_timestamp: 1743676235635
                        name: Corporate Sensor 11
                        category: advanced
                        description: Policy detected configured violation monitoring violation activity activity traffic.
                        severity: medium
                        source: example-source
                        host_name: Primary Sensor 69
                        user_name: jsmith
                        action: deny
                        alert_type: standard
                        resolution_status: enabled
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /xql/start_xql_query:
    post:
      operationId: startXqlQuery
      summary: Palo Alto Networks Execute XQL Query
      description: >-
        Initiates an XQL (Extended Query Language) query against the XSIAM
        data lake which includes endpoint telemetry, network logs, cloud
        activity, and ingested SIEM data. Returns a query ID for retrieving
        results asynchronously.
      tags:
      - XQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - query
                  properties:
                    query:
                      type: string
                      description: XQL query string to execute.
                    timeframe:
                      type: object
                      properties:
                        relativeTime:
                          type: string
                          description: >-
                            Relative time range (e.g., last_24_hours,
                            last_7_days, last_30_days).
                        startTime:
                          type: integer
                          description: Absolute start time as Unix epoch milliseconds.
                        endTime:
                          type: integer
                          description: Absolute end time as Unix epoch milliseconds.
                    max_results:
                      type: integer
                      default: 1000
                      maximum: 10000
            examples:
              StartXqlQueryRequestExample:
                summary: Default startXqlQuery request
                x-microcks-default: true
                value:
                  request_data:
                    query: example-query
                    timeframe:
                      relativeTime: example-relativeTime
                      startTime: 1731765538775
                      endTime: 1741778638340
                    max_results: 1000
      responses:
        '200':
          description: XQL query initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: string
                    description: Query execution ID for retrieving results.
              examples:
                StartXqlQuery200Example:
                  summary: Default startXqlQuery 200 response
                  x-microcks-default: true
                  value:
                    reply: example-reply
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /xql/get_query_results:
    post:
      operationId: getXqlQueryResults
      summary: Palo Alto Networks Get XQL Query Results
      description: >-
        Retrieves the results of an XQL query previously initiated via
        start_xql_query. Poll until status is SUCCESS or FAILED.
      tags:
      - XQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - query_id
                  properties:
                    query_id:
                      type: string
                      description: Query ID returned by start_xql_query.
                    pending_duration:
                      type: integer
                      description: Seconds to wait for query completion before returning.
                      default: 0
                    max_results:
                      type: integer
                      default: 1000
                    format:
                      type: string
                      enum:
                      - json
                      - json_simple
            examples:
              GetXqlQueryResultsRequestExample:
                summary: Default getXqlQueryResults request
                x-microcks-default: true
                value:
                  request_data:
                    query_id: '568519'
                    pending_duration: 0
                    max_results: 1000
                    format: json
      responses:
        '200':
          description: XQL query results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - PENDING
                        - SUCCESS
                        - FAILED
                        - CANCELED
                      number_of_results:
                        type: integer
                      query_cost:
                        type: object
                        additionalProperties:
                          type: number
                      remaining_quota:
                        type: number
                      results:
                        type: object
                        properties:
                          data:
                            type: array
                            items:
                              type: object
                              additionalProperties: true
              examples:
                GetXqlQueryResults200Example:
                  summary: Default getXqlQueryResults 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      status: SUCCESS
                      number_of_results: 530
                      query_cost: {}
                      remaining_quota: 45.6
                      results:
                        data:
                        - {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /assets/list_assets:
    post:
      operationId: listAssets
      summary: Palo Alto Networks List Assets
      description: >-
        Returns a list of assets discovered and tracked by XSIAM. Assets
        represent devices, cloud resources, users, and service accounts observed
        in the environment. Supports filtering by asset type, operating system,
        and risk score.
      tags:
      - Assets
      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:
              ListAssetsRequestExample:
                summary: Default listAssets request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: eq
                      value: example-value
                    - field: example-field
                      operator: eq
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: desc
      responses:
        '200':
          description: Assets returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      assets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Asset'
              examples:
                ListAssets200Example:
                  summary: Default listAssets 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 379
                      result_count: 575
                      assets:
                      - asset_id: '172266'
                        asset_name: Production Policy 57
                        asset_type: DEVICE
                        operating_system: Ubuntu 22.04
                        ip_addresses: &id005
                        - 10.89.140.152
                        risk_score: 6.34
                        first_seen: 751
                        last_seen: 24
                        tags: &id006
                        - critical-asset
                        sources: &id007
                        - example-sources_item
                        - example-sources_item
        '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 XSIAM protection. Supports
        filtering by endpoint ID, hostname, IP address, operating system, and
        agent connection 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: eq
                      value: example-value
                    - field: example-field
                      operator: eq
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: desc
      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: 837
                      result_count: 336
                      endpoints:
                      - endpoint_id: '305959'
                        endpoint_name: Primary Firewall 16
                        endpoint_type: WORKSTATION
                        endpoint_status: UNINSTALLED
                        os_type: AGENT_OS_LINUX
                        ip: &id003
                        - example-ip_item
                        - example-ip_item
                        users: &id004
                        - example-users_item
                        - example-users_item
                        domain: api.acme-systems.org
                        first_seen: 351
                        last_seen: 449
                        endpoint_version: 4.6.8
                        content_version: 7.3.2
                        is_isolated: AGENT_UNISOLATED
                        scan_status: running
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /audits/management_logs/get_management_logs:
    post:
      operationId: getManagementLogs
      summary: Palo Alto Networks Get Audit Management Logs
      description: >-
        Retrieves audit management logs recording administrative actions
        performed in the XSIAM console, including user logins, policy changes,
        data source configuration, and API key management.
      tags:
      - Audit
      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:
              GetManagementLogsRequestExample:
                summary: Default getManagementLogs request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: eq
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: desc
      responses:
        '200':
          description: Management logs returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AuditLog'
              examples:
                GetManagementLogs200Example:
                  summary: Default getManagementLogs 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 883
                      result_count: 794
                      data:
                      - timestamp: 1744173019855
                        actor_primary_username: soc-analyst
                        actor_email: example-actor_email
                        actor_type: User
                        sub_type: custom
                        result: FAIL
                        reason: Suspicious investigation alert traffic detected violation alert configured threat Security.
                        ip: 10.224.166.122
                        description: Violation firewall firewall detected incident endpoint policy.
                      - timestamp: 1744173019855
                        actor_primary_username: soc-analyst
                        actor_email: example-actor_email
                        actor_type: User
                        sub_type: custom
                        result: FAIL
                        reason: Suspicious investigation alert traffic detected violation alert configured threat Security.
                        ip: 10.224.166.122
                        description: Violation firewall firewall detected incident endpoint policy.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ingestion/datasources:
    post:
      operationId: configureDatasource
      summary: Palo Alto Networks Configure Data Source
      description: >-
        Configures a new data source for log ingestion into XSIAM. Data sources
        define the schema, parsing rules, and normalization mappings for
        third-party log formats. Enables XSIAM to ingest and correlate data
        from firewalls, cloud platforms, SaaS applications, and custom sources.
      tags:
      - Ingestion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - name
                  - vendor
                  - product
                  properties:
                    name:
                      type: string
                      description: Unique name for this data source configuration.
                    vendor:
                      type: string
                      description: Vendor name of the data source (e.g., Palo Alto Networks).
                    product:
                      type: string
                      description: Product name (e.g., PAN-OS, Prisma Access).
                    type:
                      type: string
                      enum:
                      - syslog
                      - https
                      - api
                      - file
                      description: Ingestion method for this data source.
                    parsing_rule:
                      type: string
                      description: >-
                        XDL (XSIAM Definition Language) parsing rule for
                        extracting fields from raw log data.
                    mapping_fields:
                      type: object
                      description: Field name mapping from source fields to XSIAM schema fields.
                      additionalProperties:
                        type: string
                    enabled:
                      type: boolean
                      default: true
            examples:
              ConfigureDatasourceRequestExample:
                summary: Default configureDatasource request
                x-microcks-default: true
                value:
                  request_data:
                    name: Staging Policy 70
                    vendor: Palo Alto Networks
                    product: example-product
                    type: syslog
                    parsing_rule: example-parsing_rule
                    mapping_fields: {}
                    enabled: true
      responses:
        '200':
          description: Data source configured successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      datasource_id:
                        type: string
                        description: Unique identifier assigned to the new data source.
                      name:
                        type: string
                      status:
                        type: string
                        enum:
                        - ACTIVE
                        - PENDING
                        - ERROR
              examples:
                ConfigureDatasource200Example:
                  summary: Default configureDatasource 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      datasource_id: '995974'
                      name: Corporate Policy 49
                      status: PENDING
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    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
        allowli

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