Cortex XSOAR API

openapi: 3.1.0
info:
  title: Palo Alto Networks Cortex XSOAR REST API
  description: >-
    REST API for the Cortex XSOAR (formerly Demisto) security orchestration,
    automation, and response (SOAR) platform. Provides programmatic access to
    incidents, investigations, playbooks, entries, and integrations. Enables
    automation of security workflows, creation and management of incidents,
    execution of playbooks, and integration with third-party security tools.
    Authentication uses an API key passed in the Authorization header. API keys
    are generated from the XSOAR settings under Integrations > API Keys.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/cortex/docs/xsoar/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://{xsoar-server}
  description: Cortex XSOAR server endpoint.
  variables:
    xsoar-server:
      description: Hostname or IP address of the Cortex XSOAR server.
      default: xsoar.example.com
security:
- apiKey: []
tags:
- name: Entries
  description: Investigation entry (work note) management.
- name: Incidents
  description: Incident creation, retrieval, search, and update operations.
- name: Integrations
  description: Integration and instance management.
- name: Investigations
  description: Investigation management.
- name: Playbooks
  description: Playbook listing and execution.
paths:
  /incident:
    post:
      operationId: createIncident
      summary: Palo Alto Networks Create Incident
      description: >-
        Creates a new incident in Cortex XSOAR. Incidents represent security
        events requiring investigation and response. Specify the incident type,
        severity, name, and any custom fields defined for the incident type.
        If an associated playbook is configured for the incident type, it starts
        automatically.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIncidentRequest'
            examples:
              CreateIncidentRequestExample:
                summary: Default createIncident request
                x-microcks-default: true
                value:
                  name: Corporate Gateway 34
                  type: custom
                  severity: 2
                  owner: example-owner
                  occurred: '2025-12-19T01:48:14Z'
                  details: Traffic rule network firewall endpoint incident network incident configured firewall activity.
                  labels: &id009
                  - type: advanced
                    value: example-value
                  createInvestigation: true
                  CustomFields: &id010 {}
                  rawJson: example-rawJson
      responses:
        '200':
          description: Incident created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              examples:
                CreateIncident200Example:
                  summary: Default createIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Branch Firewall 02
                    type: custom
                    status: 2
                    severity: 5
                    owner: example-owner
                    created: '2026-04-27T13:10:38Z'
                    modified: '2026-02-28T09:07:32Z'
                    occurred: '2026-07-07T08:02:17Z'
                    closed: '2025-06-22T23:38:50Z'
                    closeReason: example-closeReason
                    closeNotes: Malware firewall on activity applied investigation suspicious detected activity.
                    labels: &id001
                    - type: custom
                      value: example-value
                    details: Suspicious firewall detected configured suspicious network detected blocked suspicious.
                    investigationId: '720788'
                    playbookId: '265379'
                    sourceInstance: example-sourceInstance
                    sourceBrand: example-sourceBrand
                    rawJson: example-rawJson
                    CustomFields: &id002 {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incidents/search:
    get:
      operationId: searchIncidentsGet
      summary: Palo Alto Networks Search Incidents (GET)
      description: >-
        Returns incidents matching query criteria specified as URL query
        parameters. Supports filtering by keyword, status, severity, type,
        and time range. For complex queries use POST /incidents/search.
      tags:
      - Incidents
      parameters:
      - name: query
        in: query
        description: >-
          Lucene query string to filter incidents (e.g., status:Active AND
          severity:High).
        schema:
          type: string
        example: example-query
      - name: size
        in: query
        description: Maximum number of incidents to return.
        schema:
          type: integer
          default: 10
          maximum: 100
        example: 10
      - name: fromdate
        in: query
        description: Filter incidents created after this date (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2025-09-17T20:14:07Z'
      - name: todate
        in: query
        description: Filter incidents created before this date (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2025-05-07T00:33:09Z'
      - name: page
        in: query
        description: Page number for pagination (zero-based).
        schema:
          type: integer
          default: 0
        example: 0
      responses:
        '200':
          description: Incidents returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSearchResponse'
              examples:
                SearchIncidentsGet200Example:
                  summary: Default searchIncidentsGet 200 response
                  x-microcks-default: true
                  value:
                    total: &id003
                      value: 316
                      relation: example-relation
                    incidents: &id004
                    - id: example-id
                      name: Branch Firewall 02
                      type: custom
                      status: 2
                      severity: 5
                      owner: example-owner
                      created: '2026-04-27T13:10:38Z'
                      modified: '2026-02-28T09:07:32Z'
                      occurred: '2026-07-07T08:02:17Z'
                      closed: '2025-06-22T23:38:50Z'
                      closeReason: example-closeReason
                      closeNotes: Malware firewall on activity applied investigation suspicious detected activity.
                      labels: *id001
                      details: Suspicious firewall detected configured suspicious network detected blocked suspicious.
                      investigationId: '720788'
                      playbookId: '265379'
                      sourceInstance: example-sourceInstance
                      sourceBrand: example-sourceBrand
                      rawJson: example-rawJson
                      CustomFields: *id002
                    searchResultTotal: 847
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: searchIncidentsPost
      summary: Palo Alto Networks Search Incidents (POST)
      description: >-
        Searches for incidents using a structured filter in the request body.
        Supports advanced filtering, field selection, sorting, and pagination.
        Preferred over GET for complex queries.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentSearchRequest'
            examples:
              SearchIncidentsPostRequestExample:
                summary: Default searchIncidentsPost request
                x-microcks-default: true
                value:
                  filter: &id012
                    query: example-query
                    status:
                    - 427
                    sort:
                    - field: example-field
                      asc: true
                    period:
                      byFrom: '2026-11-24T23:01:39Z'
                      byTo: '2025-06-05T03:13:28Z'
                  fromDate: '2025-04-24T04:56:15Z'
                  toDate: '2024-07-10T05:59:35Z'
                  size: 10
                  page: 0
      responses:
        '200':
          description: Incidents returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSearchResponse'
              examples:
                SearchIncidentsPost200Example:
                  summary: Default searchIncidentsPost 200 response
                  x-microcks-default: true
                  value:
                    total: *id003
                    incidents: *id004
                    searchResultTotal: 847
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incident/{id}:
    get:
      operationId: getIncident
      summary: Palo Alto Networks Get Incident
      description: Returns a specific incident by its unique identifier, including all fields and metadata.
      tags:
      - Incidents
      parameters:
      - $ref: '#/components/parameters/incidentId'
      responses:
        '200':
          description: Incident returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              examples:
                GetIncident200Example:
                  summary: Default getIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Branch Firewall 02
                    type: custom
                    status: 2
                    severity: 5
                    owner: example-owner
                    created: '2026-04-27T13:10:38Z'
                    modified: '2026-02-28T09:07:32Z'
                    occurred: '2026-07-07T08:02:17Z'
                    closed: '2025-06-22T23:38:50Z'
                    closeReason: example-closeReason
                    closeNotes: Malware firewall on activity applied investigation suspicious detected activity.
                    labels: *id001
                    details: Suspicious firewall detected configured suspicious network detected blocked suspicious.
                    investigationId: '720788'
                    playbookId: '265379'
                    sourceInstance: example-sourceInstance
                    sourceBrand: example-sourceBrand
                    rawJson: example-rawJson
                    CustomFields: *id002
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incident/update:
    post:
      operationId: updateIncident
      summary: Palo Alto Networks Update Incident
      description: >-
        Updates one or more fields of an existing incident. Only the fields
        provided in the request body are modified. Supports updating status,
        severity, owner, labels, and custom fields.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIncidentRequest'
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  id: example-id
                  version: 134
                  status: 2
                  severity: 3
                  owner: example-owner
                  details: Threat detected violation endpoint investigation traffic policy policy activity.
                  closeReason: example-closeReason
                  closeNotes: Rule endpoint activity detected violation malware alert on violation threat.
                  CustomFields: &id011 {}
      responses:
        '200':
          description: Incident updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Branch Firewall 02
                    type: custom
                    status: 2
                    severity: 5
                    owner: example-owner
                    created: '2026-04-27T13:10:38Z'
                    modified: '2026-02-28T09:07:32Z'
                    occurred: '2026-07-07T08:02:17Z'
                    closed: '2025-06-22T23:38:50Z'
                    closeReason: example-closeReason
                    closeNotes: Malware firewall on activity applied investigation suspicious detected activity.
                    labels: *id001
                    details: Suspicious firewall detected configured suspicious network detected blocked suspicious.
                    investigationId: '720788'
                    playbookId: '265379'
                    sourceInstance: example-sourceInstance
                    sourceBrand: example-sourceBrand
                    rawJson: example-rawJson
                    CustomFields: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /entry:
    post:
      operationId: addEntry
      summary: Palo Alto Networks Add Entry to Investigation
      description: >-
        Adds a work note or entry to an investigation's war room. Entries can
        be notes, commands, files, or other content types. The war room serves
        as the collaborative workspace for the incident investigation team.
      tags:
      - Entries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntryRequest'
            examples:
              AddEntryRequestExample:
                summary: Default addEntry request
                x-microcks-default: true
                value:
                  investigationId: '274080'
                  data: example-data
                  markdown: false
                  tags: &id013
                  - critical-asset
                  - production
      responses:
        '200':
          description: Entry added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entry'
              examples:
                AddEntry200Example:
                  summary: Default addEntry 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    investigationId: '215099'
                    type: 140
                    user: example-user
                    created: '2024-07-22T09:20:31Z'
                    modified: '2025-02-16T15:12:04Z'
                    contents: example-contents
                    humanReadable: example-humanReadable
                    tags: &id005
                    - production
                    - pci-scope
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /investigations/{id}:
    get:
      operationId: getInvestigation
      summary: Palo Alto Networks Get Investigation
      description: >-
        Returns the full details of an investigation including all war room
        entries, playbook status, and associated incidents.
      tags:
      - Investigations
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the investigation.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Investigation returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
              examples:
                GetInvestigation200Example:
                  summary: Default getInvestigation 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Corporate Agent 49
                    status: 611
                    incidentId: '613705'
                    created: '2025-05-10T09:56:48Z'
                    modified: '2026-07-27T07:59:00Z'
                    entries: &id006
                    - id: example-id
                      investigationId: '215099'
                      type: 140
                      user: example-user
                      created: '2024-07-22T09:20:31Z'
                      modified: '2025-02-16T15:12:04Z'
                      contents: example-contents
                      humanReadable: example-humanReadable
                      tags: *id005
                    playbookId: '207029'
                    runningPlaybooks: &id007
                    - example-runningPlaybooks_item
                    - example-runningPlaybooks_item
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /investigation/add:
    post:
      operationId: createInvestigation
      summary: Palo Alto Networks Create Investigation
      description: >-
        Creates a new investigation attached to an existing incident. Multiple
        investigations can be created for a single incident to track separate
        analytical threads.
      tags:
      - Investigations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - incidentId
              properties:
                incidentId:
                  type: string
                  description: ID of the incident to attach the investigation to.
                name:
                  type: string
                  description: Optional name for the investigation.
            examples:
              CreateInvestigationRequestExample:
                summary: Default createInvestigation request
                x-microcks-default: true
                value:
                  incidentId: '974282'
                  name: Primary Gateway 48
      responses:
        '200':
          description: Investigation created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
              examples:
                CreateInvestigation200Example:
                  summary: Default createInvestigation 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Corporate Agent 49
                    status: 611
                    incidentId: '613705'
                    created: '2025-05-10T09:56:48Z'
                    modified: '2026-07-27T07:59:00Z'
                    entries: *id006
                    playbookId: '207029'
                    runningPlaybooks: *id007
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /playbook:
    get:
      operationId: listPlaybooks
      summary: Palo Alto Networks List Playbooks
      description: >-
        Returns all playbooks available in the Cortex XSOAR instance. Playbooks
        define automated response workflows that execute tasks, run integrations,
        and perform actions in response to incident conditions.
      tags:
      - Playbooks
      parameters:
      - name: query
        in: query
        description: Filter playbooks by name or keyword.
        schema:
          type: string
        example: example-query
      responses:
        '200':
          description: Playbooks returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Playbook'
              examples:
                ListPlaybooks200Example:
                  summary: Default listPlaybooks 200 response
                  x-microcks-default: true
                  value:
                  - id: example-id
                    name: Production Policy 92
                    version: 797
                    description: Incident blocked suspicious policy violation malware on alert blocked on firewall.
                    tags: &id014
                    - production
                    - pci-scope
                    fromVersion: 6.6.6
                    toVersion: 9.3.8
                    deprecated: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /playbook/run:
    post:
      operationId: runPlaybook
      summary: Palo Alto Networks Run Playbook
      description: >-
        Executes a playbook against a specified incident. The playbook runs
        asynchronously and its progress can be monitored through the
        investigation's war room entries.
      tags:
      - Playbooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - incidentId
              - playbookId
              properties:
                incidentId:
                  type: string
                  description: ID of the incident to run the playbook on.
                playbookId:
                  type: string
                  description: ID of the playbook to execute.
                version:
                  type: integer
                  description: Specific playbook version to run (defaults to latest).
            examples:
              RunPlaybookRequestExample:
                summary: Default runPlaybook request
                x-microcks-default: true
                value:
                  incidentId: '421176'
                  playbookId: '832935'
                  version: 741
      responses:
        '200':
          description: Playbook execution initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Playbook run ID.
                  status:
                    type: string
                    enum:
                    - running
                    - completed
                    - failed
                    - waiting
              examples:
                RunPlaybook200Example:
                  summary: Default runPlaybook 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    status: failed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /integration/search:
    get:
      operationId: searchIntegrations
      summary: Palo Alto Networks Search Integrations
      description: >-
        Returns a list of available integration packs installed in the Cortex
        XSOAR instance. Integrations provide connectivity to third-party
        security tools and platforms.
      tags:
      - Integrations
      parameters:
      - name: query
        in: query
        description: Search query to filter integrations by name or category.
        schema:
          type: string
        example: example-query
      - name: page
        in: query
        schema:
          type: integer
          default: 0
        example: 0
      - name: size
        in: query
        schema:
          type: integer
          default: 50
        example: 50
      responses:
        '200':
          description: Integrations returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  configurations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Integration'
                  total:
                    type: integer
              examples:
                SearchIntegrations200Example:
                  summary: Default searchIntegrations 200 response
                  x-microcks-default: true
                  value:
                    configurations:
                    - id: example-id
                      name: Corporate Policy 44
                      display: example-display
                      category: standard
                      description: Malware malware threat suspicious alert alert violation incident activity detected policy rule.
                      version: 338
                      fromVersion: 10.3.1
                      deprecated: false
                      beta: true
                    - id: example-id
                      name: Corporate Policy 44
                      display: example-display
                      category: standard
                      description: Malware malware threat suspicious alert alert violation incident activity detected policy rule.
                      version: 338
                      fromVersion: 10.3.1
                      deprecated: false
                      beta: true
                    total: 906
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /settings/integration/search:
    post:
      operationId: searchIntegrationInstances
      summary: Palo Alto Networks Search Integration Instances
      description: >-
        Returns a list of configured integration instances. Each instance
        represents a configured connection to a specific tool using a particular
        integration pack. Supports filtering by integration name and enabled status.
      tags:
      - Integrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Search query to filter instances by name or brand.
                page:
                  type: integer
                  default: 0
                size:
                  type: integer
                  default: 50
            examples:
              SearchIntegrationInstancesRequestExample:
                summary: Default searchIntegrationInstances request
                x-microcks-default: true
                value:
                  query: example-query
                  page: 0
                  size: 50
      responses:
        '200':
          description: Integration instances returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instances:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationInstance'
                  total:
                    type: integer
              examples:
                SearchIntegrationInstances200Example:
                  summary: Default searchIntegrationInstances 200 response
                  x-microcks-default: true
                  value:
                    instances:
                    - id: example-id
                      name: Staging Firewall 25
                      brand: example-brand
                      enabled: 'false'
                      isIntegrationScript: true
                      incomingMapperId: '599642'
                      mappingId: '597859'
                      configuration: &id008 {}
                    - id: example-id
                      name: Staging Firewall 25
                      brand: example-brand
                      enabled: 'false'
                      isIntegrationScript: true
                      incomingMapperId: '599642'
                      mappingId: '597859'
                      configuration: *id008
                    total: 629
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Cortex XSOAR API key. Generate from Settings > Integrations > API Keys
        in the XSOAR console. Pass the key directly as the Authorization header
        value (no Bearer prefix required for standard API keys).
  parameters:
    incidentId:
      name: id
      in: path
      required: true
      description: Unique identifier of the incident.
      schema:
        type: string
  responses:
    BadRequest:
      description: Malformed request or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Incident:
      type: object
      description: A Cortex XSOAR incident representing a security event under investigation.
      properties:
        id:
          type: string
          description: Unique incident identifier.
          readOnly: true
          example: example-id
        name:
          type: string
          description: Incident name or title.
          example: Branch Firewall 02
        type:
          type: string
          description: Incident type (maps to an incident type definition).
          example: custom
        status:
          type: integer
          description: >-
            Incident status code: 0 (Pending), 1 (Active), 2 (Done),
            3 (Archive).
          enum:
          - 0
          - 1
          - 2
          - 3
          example: 2
        severity:
          type: integer
          description: >-
            Severity level: 0 (Unknown), 1 (Informational), 2 (Low),
            3 (Medium), 4 (High), 5 (Critical).
          enum:
 

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