openapi: 3.1.0
info:
  title: McAfee ePO 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
externalDocs:
  description: McAfee ePO Web API Reference Guide
  url: https://docs.mcafee.com/bundle/epolicy-orchestrator-web-api-reference-guide
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
tags:
  - name: Core
    description: Core server operations and authentication
  - name: Policies
    description: Manage and assign security policies
  - name: Queries
    description: Execute ePO queries and retrieve results
  - name: Software
    description: Manage software repositories and packages
  - name: System Groups
    description: Manage the ePO System Tree groups
  - name: Systems
    description: Manage endpoints and systems registered in ePO
  - name: Tasks
    description: Manage client tasks and server tasks
  - name: Threat Events
    description: Retrieve threat event data from managed endpoints
security:
  - basicAuth: []
paths:
  /core.help:
    get:
      operationId: coreHelp
      summary: McAfee List available API commands
      description: >-
        Returns a list of all available remote API commands on the ePO server
        with their descriptions and parameters.
      tags:
        - Core
      parameters:
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of available API commands
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiCommand'
        '401':
          description: Authentication failed
  /system.find:
    get:
      operationId: systemFind
      summary: McAfee Search for systems
      description: >-
        Search for managed systems in the ePO System Tree matching specified
        criteria such as name, IP address, tags, or custom properties.
      tags:
        - Systems
      parameters:
        - name: searchText
          in: query
          required: true
          description: Search string to match against system names, IP addresses, or other properties
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of matching systems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/System'
        '401':
          description: Authentication failed
  /system.findTag:
    get:
      operationId: systemFindTag
      summary: McAfee Find systems by tag
      description: >-
        Retrieve a list of systems that have a specific tag applied.
      tags:
        - Systems
      parameters:
        - name: tagName
          in: query
          required: true
          description: Name of the tag to search for
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of systems with the specified tag
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/System'
        '401':
          description: Authentication failed
  /system.applyTag:
    post:
      operationId: systemApplyTag
      summary: McAfee Apply a tag to systems
      description: >-
        Apply a tag to one or more systems identified by name or ID.
      tags:
        - Systems
      parameters:
        - name: names
          in: query
          required: true
          description: Comma-separated list of system names or IDs
          schema:
            type: string
        - name: tagName
          in: query
          required: true
          description: Name of the tag to apply
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Tag applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /system.clearTag:
    post:
      operationId: systemClearTag
      summary: McAfee Remove a tag from systems
      description: >-
        Remove a tag from one or more systems identified by name or ID.
      tags:
        - Systems
      parameters:
        - name: names
          in: query
          required: true
          description: Comma-separated list of system names or IDs
          schema:
            type: string
        - name: tagName
          in: query
          required: true
          description: Name of the tag to remove
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Tag removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /epogroup.find:
    get:
      operationId: epogroupFind
      summary: McAfee Find system tree groups
      description: >-
        Search for groups in the ePO System Tree by name or other criteria.
      tags:
        - System Groups
      parameters:
        - name: searchText
          in: query
          required: false
          description: Search string to match against group names
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of matching groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SystemGroup'
        '401':
          description: Authentication failed
  /epogroup.moveSystem:
    post:
      operationId: epogroupMoveSystem
      summary: McAfee Move a system to a different group
      description: >-
        Move one or more systems from their current location in the System Tree
        to a specified target group.
      tags:
        - System Groups
      parameters:
        - name: names
          in: query
          required: true
          description: Comma-separated list of system names to move
          schema:
            type: string
        - name: parentGroupId
          in: query
          required: true
          description: ID of the target parent group
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Systems moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /policy.find:
    get:
      operationId: policyFind
      summary: McAfee Search for policies
      description: >-
        Search for security policies configured in ePO, optionally filtered by
        product or policy type.
      tags:
        - Policies
      parameters:
        - name: searchText
          in: query
          required: false
          description: Search string to match against policy names
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of matching policies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Policy'
        '401':
          description: Authentication failed
  /policy.assignToSystem:
    post:
      operationId: policyAssignToSystem
      summary: McAfee Assign a policy to a system
      description: >-
        Assign a specific policy to one or more systems, overriding the
        inherited group policy.
      tags:
        - Policies
      parameters:
        - name: names
          in: query
          required: true
          description: Comma-separated list of system names
          schema:
            type: string
        - name: productId
          in: query
          required: true
          description: Product ID for the policy
          schema:
            type: string
        - name: typeId
          in: query
          required: true
          description: Policy type ID
          schema:
            type: string
        - name: objectId
          in: query
          required: true
          description: Policy object ID
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Policy assigned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /policy.assignToGroup:
    post:
      operationId: policyAssignToGroup
      summary: McAfee Assign a policy to a group
      description: >-
        Assign a specific policy to a System Tree group, which is then inherited
        by all child systems and sub-groups.
      tags:
        - Policies
      parameters:
        - name: groupId
          in: query
          required: true
          description: Target group ID
          schema:
            type: integer
        - name: productId
          in: query
          required: true
          description: Product ID for the policy
          schema:
            type: string
        - name: typeId
          in: query
          required: true
          description: Policy type ID
          schema:
            type: string
        - name: objectId
          in: query
          required: true
          description: Policy object ID
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Policy assigned to group successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /clienttask.find:
    get:
      operationId: clienttaskFind
      summary: McAfee Search for client tasks
      description: >-
        Search for client tasks that can be deployed to managed systems.
      tags:
        - Tasks
      parameters:
        - name: searchText
          in: query
          required: false
          description: Search string to match against task names
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of matching client tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClientTask'
        '401':
          description: Authentication failed
  /clienttask.run:
    post:
      operationId: clienttaskRun
      summary: McAfee Run a client task on systems
      description: >-
        Execute a client task immediately on one or more specified systems.
      tags:
        - Tasks
      parameters:
        - name: names
          in: query
          required: true
          description: Comma-separated list of system names
          schema:
            type: string
        - name: productId
          in: query
          required: true
          description: Product ID for the task
          schema:
            type: string
        - name: taskId
          in: query
          required: true
          description: Client task ID to execute
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Task execution initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
  /core.executeQuery:
    get:
      operationId: coreExecuteQuery
      summary: McAfee Execute a saved query
      description: >-
        Execute a previously saved ePO query by ID and return the results. Queries
        can retrieve data about systems, events, policies, and other ePO objects.
      tags:
        - Queries
      parameters:
        - name: queryId
          in: query
          required: true
          description: ID of the saved query to execute
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          description: Authentication failed
        '404':
          description: Query not found
  /core.listQueries:
    get:
      operationId: coreListQueries
      summary: McAfee List saved queries
      description: >-
        Retrieve a list of all saved queries available on the ePO server.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of saved queries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SavedQuery'
        '401':
          description: Authentication failed
  /detectedsystem.find:
    get:
      operationId: detectedsystemFind
      summary: McAfee Find threat events
      description: >-
        Search for detected threat events across managed systems, returning
        details about malware detections, intrusion attempts, and other security events.
      tags:
        - Threat Events
      parameters:
        - name: searchText
          in: query
          required: false
          description: Search text to filter threat events
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of threat events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ThreatEvent'
        '401':
          description: Authentication failed
  /repository.findPackages:
    get:
      operationId: repositoryFindPackages
      summary: McAfee Find software packages
      description: >-
        Search for software packages in the ePO master repository, including
        DAT files, engine updates, and product packages.
      tags:
        - Software
      parameters:
        - name: searchText
          in: query
          required: false
          description: Search string to filter packages
          schema:
            type: string
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of matching packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SoftwarePackage'
        '401':
          description: Authentication failed
  /scheduler.listServerTasks:
    get:
      operationId: schedulerListServerTasks
      summary: McAfee List server tasks
      description: >-
        Retrieve a list of all configured server tasks in ePO, including
        pull tasks, replication tasks, and custom automation tasks.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: List of server tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerTask'
        '401':
          description: Authentication failed
  /scheduler.runServerTask:
    post:
      operationId: schedulerRunServerTask
      summary: McAfee Run a server task
      description: >-
        Execute a server task immediately by its ID.
      tags:
        - Tasks
      parameters:
        - name: taskId
          in: query
          required: true
          description: ID of the server task to execute
          schema:
            type: integer
        - $ref: '#/components/parameters/outputType'
      responses:
        '200':
          description: Server task execution initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResult'
        '401':
          description: Authentication failed
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using ePO administrator credentials.
        Credentials are transmitted as a Base64-encoded username:password pair.
  parameters:
    outputType:
      name: :output
      in: query
      required: false
      description: >-
        Output format for the response. Defaults to JSON when not specified.
      schema:
        type: string
        enum:
          - json
          - xml
          - terse
          - verbose
        default: json
  schemas:
    System:
      type: object
      properties:
        EPOComputerProperties.ParentID:
          type: integer
          description: Parent group ID in the System Tree
        EPOComputerProperties.ComputerName:
          type: string
          description: NetBIOS computer name
        EPOComputerProperties.IPAddress:
          type: string
          description: IP address of the system
        EPOComputerProperties.OSType:
          type: string
          description: Operating system type
        EPOComputerProperties.OSVersion:
          type: string
          description: Operating system version
        EPOComputerProperties.DomainName:
          type: string
          description: Domain or workgroup name
        EPOComputerProperties.UserName:
          type: string
          description: Logged-in user name
        EPOComputerProperties.Tags:
          type: string
          description: Comma-separated list of applied tags
        EPOLeafNode.AgentGUID:
          type: string
          description: Unique McAfee Agent GUID
        EPOLeafNode.AgentVersion:
          type: string
          description: Installed McAfee Agent version
        EPOLeafNode.LastUpdate:
          type: string
          format: date-time
          description: Last agent-server communication time
        EPOLeafNode.ManagedState:
          type: string
          description: Management state of the system
    SystemGroup:
      type: object
      properties:
        groupId:
          type: integer
          description: Unique group ID
        groupPath:
          type: string
          description: Full path in the System Tree
        groupName:
          type: string
          description: Name of the group
    Policy:
      type: object
      properties:
        objectId:
          type: integer
          description: Policy object ID
        objectName:
          type: string
          description: Policy name
        productId:
          type: string
          description: Product ID the policy belongs to
        typeId:
          type: string
          description: Policy type identifier
        productName:
          type: string
          description: Display name of the product
    ClientTask:
      type: object
      properties:
        objectId:
          type: integer
          description: Task object ID
        objectName:
          type: string
          description: Task name
        productId:
          type: string
          description: Product ID the task belongs to
        typeId:
          type: string
          description: Task type identifier
        productName:
          type: string
          description: Display name of the product
    ServerTask:
      type: object
      properties:
        id:
          type: integer
          description: Server task ID
        name:
          type: string
          description: Server task name
        description:
          type: string
          description: Server task description
        enabled:
          type: boolean
          description: Whether the task is enabled
        nextRunTime:
          type: string
          format: date-time
          description: Next scheduled run time
    SavedQuery:
      type: object
      properties:
        id:
          type: integer
          description: Query ID
        name:
          type: string
          description: Query name
        description:
          type: string
          description: Query description
        createdBy:
          type: string
          description: User who created the query
        groupName:
          type: string
          description: Query group name
    ThreatEvent:
      type: object
      properties:
        AutoID:
          type: integer
          description: Auto-incremented event ID
        DetectedUTC:
          type: string
          format: date-time
          description: Detection time in UTC
        ReceivedUTC:
          type: string
          format: date-time
          description: Time the event was received by ePO
        ThreatName:
          type: string
          description: Name of the detected threat
        ThreatType:
          type: string
          description: Type of threat (e.g., virus, trojan, PUP)
        ThreatSeverity:
          type: integer
          description: Severity level of the threat
        ThreatActionTaken:
          type: string
          description: Action taken on the threat (e.g., cleaned, deleted, quarantined)
        SourceHostName:
          type: string
          description: Hostname of the system where the threat was detected
        SourceIPV4:
          type: string
          description: IPv4 address of the source system
        TargetFileName:
          type: string
          description: File path of the affected file
        AnalyzerName:
          type: string
          description: Name of the product that detected the threat
        AnalyzerVersion:
          type: string
          description: Version of the detecting product
    SoftwarePackage:
      type: object
      properties:
        productId:
          type: string
          description: Package product ID
        packageType:
          type: string
          description: Package type (e.g., DAT, Engine, Product)
        packageVersion:
          type: string
          description: Package version string
        packageName:
          type: string
          description: Display name of the package
    CommandResult:
      type: object
      properties:
        result:
          type: string
          description: Result status message
    ApiCommand:
      type: object
      properties:
        command:
          type: string
          description: Command name
        description:
          type: string
          description: Command description
        parameters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              required:
                type: boolean
              description:
                type: string