openapi: 3.1.0
info:
  title: McAfee ePO Alarms Devices API
  description: McAfee ePolicy Orchestrator (ePO) REST API for centralized security management, including system management, policy assignment, task scheduling, query execution, and threat event retrieval across managed endpoints.
  version: '5.10'
  contact:
    name: McAfee Support
    url: https://www.mcafee.com/enterprise/en-us/support.html
  termsOfService: https://www.mcafee.com/enterprise/en-us/about/legal/terms-of-use.html
servers:
- url: https://{epo-server}:8443/remote
  description: McAfee ePO Server
  variables:
    epo-server:
      default: your-epo-server
      description: Hostname or IP of the ePO server
security:
- basicAuth: []
tags:
- name: Devices
  description: Manage ESM device hierarchy
paths:
  /v2/devGetDeviceList:
    post:
      operationId: getDevices
      summary: McAfee List ESM devices
      description: Retrieve the list of devices in the ESM device hierarchy, including receivers, ELM, ACE, DEM, and ADM components.
      tags:
      - Devices
      responses:
        '200':
          description: List of ESM devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EsmDevice'
        '401':
          description: Not authenticated
  /edr/v2/devices:
    get:
      operationId: listDevices
      summary: McAfee List managed devices
      description: Retrieve a paginated list of all devices managed by MVISION, including their health status, agent version, and last check-in time.
      tags:
      - Devices
      parameters:
      - name: filter[hostName]
        in: query
        required: false
        description: Filter devices by hostname
        schema:
          type: string
      - name: filter[os]
        in: query
        required: false
        description: Filter devices by operating system
        schema:
          type: string
      - name: filter[healthStatus]
        in: query
        required: false
        description: Filter by device health status
        schema:
          type: string
          enum:
          - healthy
          - unhealthy
          - inactive
      - $ref: '#/components/parameters/pageLimit'
      - $ref: '#/components/parameters/pageOffset'
      responses:
        '200':
          description: Paginated list of devices
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
        '401':
          description: Unauthorized
  /edr/v2/devices/{deviceId}:
    get:
      operationId: getDevice
      summary: McAfee Get a specific device
      description: Retrieve detailed information about a specific managed device, including installed products, agent version, and security posture.
      tags:
      - Devices
      parameters:
      - name: deviceId
        in: path
        required: true
        description: Unique device identifier
        schema:
          type: string
      responses:
        '200':
          description: Device details
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DeviceResponse'
        '401':
          description: Unauthorized
        '404':
          description: Device not found
components:
  parameters:
    pageLimit:
      name: page[limit]
      in: query
      required: false
      description: Maximum number of results to return per page
      schema:
        type: integer
        default: 20
        maximum: 100
    pageOffset:
      name: page[offset]
      in: query
      required: false
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
  schemas:
    DeviceListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Device:
      type: object
      properties:
        id:
          type: string
          description: Unique device ID
        type:
          type: string
          enum:
          - devices
        attributes:
          type: object
          properties:
            hostName:
              type: string
              description: Device hostname
            ipAddress:
              type: string
              description: Device IP address
            os:
              type: string
              description: Operating system
            osVersion:
              type: string
              description: Operating system version
            agentVersion:
              type: string
              description: MVISION agent version
            healthStatus:
              type: string
              enum:
              - healthy
              - unhealthy
              - inactive
              description: Device health status
            lastCheckIn:
              type: string
              format: date-time
              description: Last agent check-in time
            tags:
              type: array
              items:
                type: string
              description: Applied tags
    PaginationMeta:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total number of matching records
        pageLimit:
          type: integer
          description: Current page size limit
        pageOffset:
          type: integer
          description: Current offset
    DeviceResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Device'
    EsmDevice:
      type: object
      properties:
        id:
          type: integer
          description: Device ID
        name:
          type: string
          description: Device name
        ipAddress:
          type: string
          description: Device IP address
        type:
          type: string
          enum:
          - ESM
          - Receiver
          - ELM
          - ACE
          - DEM
          - ADM
          description: Device type in the ESM hierarchy
        status:
          type: string
          description: Device operational status
        model:
          type: string
          description: Hardware or virtual model
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using ePO administrator credentials. Credentials are transmitted as a Base64-encoded username:password pair.
externalDocs:
  description: McAfee ePO Web API Reference Guide
  url: https://docs.mcafee.com/bundle/epolicy-orchestrator-web-api-reference-guide