openapi: 3.1.0
info:
  title: Trellix ePO SaaS API
  description: >-
    The Trellix ePO SaaS API provides cloud-based access to ePolicy
    Orchestrator management capabilities. It enables programmatic control
    of devices, events, tags, queries, and response actions through
    the Trellix cloud management platform. Authentication uses OAuth 2.0
    client credentials with scoped permissions for each resource type.
  version: '2.0'
  contact:
    name: Trellix Support
    url: https://www.trellix.com/support/
  termsOfService: https://www.trellix.com/en-us/about/legal/terms-of-use.html
externalDocs:
  description: Trellix ePO SaaS Product Guide
  url: https://docs.trellix.com/bundle/epolicy-orchestrator-saas-product-guide
servers:
  - url: https://api.manage.trellix.com
    description: Trellix Cloud Management Platform
tags:
  - name: Devices
    description: >-
      Manage and query endpoint devices registered in ePO SaaS,
      including device attributes, agent status, and system information.
  - name: Events
    description: >-
      Retrieve threat events and security incidents detected across
      managed endpoints. Events have a 3-day retention period.
  - name: Groups
    description: >-
      Manage device groups and organizational hierarchy within the
      ePO SaaS console.
  - name: Queries
    description: >-
      Execute and manage saved queries against the ePO SaaS data
      store for reporting and analysis.
  - name: Response Actions
    description: >-
      Trigger automated response actions on managed endpoints,
      including policy enforcement and remediation tasks.
security:
  - bearerAuth: []
paths:
  /epo/v2/devices:
    get:
      operationId: listDevices
      summary: List managed devices
      description: >-
        Retrieve a paginated list of all endpoint devices registered
        and managed through ePO SaaS. Returns device attributes
        including name, agent GUID, tags, operating system, and
        last communication timestamp.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: filter
          in: query
          description: >-
            Filter expression to narrow device results by attributes
            such as name, operating system, or agent status.
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Sort order for results, specified as a field name with
            optional direction prefix (+ for ascending, - for descending).
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of managed devices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
        '403':
          description: Forbidden - insufficient scope permissions
  /epo/v2/devices/{deviceId}:
    get:
      operationId: getDevice
      summary: Get device details
      description: >-
        Retrieve detailed information about a specific managed device
        by its unique identifier. Returns comprehensive device attributes
        including hardware details, installed products, and agent status.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/deviceId'
      responses:
        '200':
          description: Device details returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized - invalid or expired access token
        '404':
          description: Device not found
  /epo/v2/events:
    get:
      operationId: listEvents
      summary: List threat events
      description: >-
        Retrieve threat events detected across managed endpoints.
        Events include malware detections, policy violations, and
        other security incidents. The data retention period for
        events is 3 days.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: since
          in: query
          description: >-
            Return events that occurred after this ISO 8601 timestamp.
            Maximum lookback is 3 days due to data retention limits.
          schema:
            type: string
            format: date-time
        - name: filter
          in: query
          description: >-
            Filter expression to narrow events by attributes such
            as severity, analyzer name, or agent GUID.
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of threat events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
        '403':
          description: Forbidden - insufficient scope permissions
  /epo/v2/tags:
    get:
      operationId: listTags
      summary: List tags
      description: >-
        Retrieve all tags configured in ePO SaaS. Tags are used to
        organize and group managed devices for policy assignment
        and reporting purposes.
      tags: []
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of configured tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
    post:
      operationId: createTag
      summary: Create a tag
      description: >-
        Create a new tag in ePO SaaS for organizing managed devices.
        Tags can be applied to devices manually or through automated
        criteria-based assignment rules.
      tags: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreate'
      responses:
        '201':
          description: Tag created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tag'
        '400':
          description: Invalid tag data
        '401':
          description: Unauthorized - invalid or expired access token
  /epo/v2/tags/{tagId}:
    get:
      operationId: getTag
      summary: Get tag details
      description: >-
        Retrieve details of a specific tag including its name,
        description, and the criteria used for automatic device
        assignment.
      tags: []
      parameters:
        - $ref: '#/components/parameters/tagId'
      responses:
        '200':
          description: Tag details returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tag'
        '401':
          description: Unauthorized - invalid or expired access token
        '404':
          description: Tag not found
    delete:
      operationId: deleteTag
      summary: Delete a tag
      description: >-
        Delete a tag from ePO SaaS. Removing a tag also removes
        the tag assignment from all associated devices.
      tags: []
      parameters:
        - $ref: '#/components/parameters/tagId'
      responses:
        '204':
          description: Tag deleted successfully
        '401':
          description: Unauthorized - invalid or expired access token
        '404':
          description: Tag not found
  /epo/v2/groups:
    get:
      operationId: listGroups
      summary: List device groups
      description: >-
        Retrieve the organizational hierarchy of device groups
        configured in ePO SaaS. Groups define the structure for
        policy inheritance and reporting scope.
      tags:
        - Groups
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of device groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
  /epo/v2/queries:
    get:
      operationId: listQueries
      summary: List saved queries
      description: >-
        Retrieve a list of saved queries available in ePO SaaS.
        Queries can be executed against the data store for reporting
        and analysis of managed endpoints and security events.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of saved queries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Query'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
  /epo/v2/queries/{queryId}/run:
    post:
      operationId: executeQuery
      summary: Execute a saved query
      description: >-
        Execute a saved query and return its results. Queries run
        against the ePO SaaS data store and can return device,
        event, or policy compliance information.
      tags:
        - Queries
      parameters:
        - $ref: '#/components/parameters/queryId'
      responses:
        '200':
          description: Query results returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: Unauthorized - invalid or expired access token
        '404':
          description: Query not found
  /epo/v2/response-actions:
    post:
      operationId: createResponseAction
      summary: Create a response action
      description: >-
        Trigger an automated response action on one or more managed
        endpoints. Response actions include policy enforcement,
        scan initiation, agent wake-up, and remediation tasks.
      tags:
        - Response Actions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseActionCreate'
      responses:
        '202':
          description: Response action accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ResponseAction'
        '400':
          description: Invalid response action request
        '401':
          description: Unauthorized - invalid or expired access token
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 access token obtained through the client credentials
        flow. Requires appropriate scope permissions such as epo.device.r,
        epo.device.w, epo.tags.r, epo.tags.w, epo.evt.r, epo.qery.g,
        epo.qery.u, epo.resp.ra, and epo.resp.ru.
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of items to return per page
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 100
    offset:
      name: offset
      in: query
      description: Number of items to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
    deviceId:
      name: deviceId
      in: path
      required: true
      description: Unique identifier of the managed device
      schema:
        type: string
    tagId:
      name: tagId
      in: path
      required: true
      description: Unique identifier of the tag
      schema:
        type: string
    queryId:
      name: queryId
      in: path
      required: true
      description: Unique identifier of the saved query
      schema:
        type: string
  schemas:
    Device:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the device
        type:
          type: string
          description: Resource type identifier
        attributes:
          type: object
          properties:
            name:
              type: string
              description: Hostname or display name of the device
            agentGuid:
              type: string
              format: uuid
              description: Unique GUID assigned to the endpoint agent
            agentVersion:
              type: string
              description: Version of the installed endpoint agent
            operatingSystem:
              type: string
              description: Operating system name and version
            ipAddress:
              type: string
              description: Primary IP address of the device
            macAddress:
              type: string
              description: Primary MAC address of the device
            domain:
              type: string
              description: Domain or workgroup the device belongs to
            userName:
              type: string
              description: Last logged-in user name
            lastUpdate:
              type: string
              format: date-time
              description: Timestamp of the last agent communication
            managed:
              type: boolean
              description: Whether the device is actively managed
            tags:
              type: array
              items:
                type: string
              description: Tags assigned to this device
    Event:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the event
        type:
          type: string
          description: Resource type identifier
        attributes:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
              description: Time the event occurred
            agentGuid:
              type: string
              format: uuid
              description: GUID of the agent that reported the event
            analyzerName:
              type: string
              description: Name of the security analyzer that detected the event
            analyzerVersion:
              type: string
              description: Version of the detecting analyzer
            threatName:
              type: string
              description: Name or identifier of the detected threat
            threatSeverity:
              type: string
              description: Severity level of the threat
            threatCategory:
              type: string
              description: Category classification of the threat
            targetFileName:
              type: string
              description: File name targeted by the threat
            targetFilePath:
              type: string
              description: Full file path of the targeted file
            detectionMethod:
              type: string
              description: Method used to detect the threat
    Tag:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the tag
        name:
          type: string
          description: Display name of the tag
        description:
          type: string
          description: Description of the tag purpose
        criteria:
          type: string
          description: >-
            Criteria expression for automatic tag assignment
            to matching devices
    TagCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name for the new tag
        description:
          type: string
          description: Description of the tag purpose
        criteria:
          type: string
          description: >-
            Optional criteria expression for automatic tag
            assignment to matching devices
    Group:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the group
        name:
          type: string
          description: Display name of the group
        parentId:
          type: string
          description: Identifier of the parent group in the hierarchy
        path:
          type: string
          description: Full path of the group in the organizational hierarchy
        deviceCount:
          type: integer
          description: Number of devices assigned to this group
    Query:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the saved query
        name:
          type: string
          description: Display name of the query
        description:
          type: string
          description: Description of what the query returns
        targetType:
          type: string
          description: The data type targeted by the query
        visibility:
          type: string
          enum:
            - public
            - private
          description: Whether the query is shared or private
    ResponseAction:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the response action
        actionType:
          type: string
          description: Type of response action triggered
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - failed
          description: Current status of the response action
        targetDevices:
          type: array
          items:
            type: string
          description: List of device identifiers targeted by the action
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the action was created
    ResponseActionCreate:
      type: object
      required:
        - actionType
        - targetDevices
      properties:
        actionType:
          type: string
          enum:
            - wake_up_agent
            - run_scan
            - enforce_policy
            - collect_data
          description: Type of response action to execute
        targetDevices:
          type: array
          items:
            type: string
          description: List of device identifiers to target
        parameters:
          type: object
          description: Additional parameters specific to the action type
    PaginationMeta:
      type: object
      properties:
        totalItems:
          type: integer
          description: Total number of items matching the query
        limit:
          type: integer
          description: Number of items per page
        offset:
          type: integer
          description: Number of items skipped