openapi: 3.1.0
info:
  title: WatchGuard Endpoint Security Management API
  description: >-
    The WatchGuard Endpoint Security Management API provides RESTful access to
    WatchGuard Endpoint Security (WES) features including device management,
    security events, risk assessment, configuration management, and license
    information. All endpoints require OAuth 2.0 bearer authentication and the
    WatchGuard-API-Key header.
  version: v1
  contact:
    name: WatchGuard Support
    url: https://www.watchguard.com/help/docs/API/Content/en-US/endpoint_security/WES_endpoint_security/v1/WES_endpoint_security.html
servers:
  - url: https://api.usa.cloud.watchguard.com/rest/endpoint-security/management/api/v1
    description: USA Region
  - url: https://api.eu.cloud.watchguard.com/rest/endpoint-security/management/api/v1
    description: EU Region
tags:
  - name: Devices
    description: Manage and query endpoint devices.
  - name: Device Actions
    description: Perform actions on endpoint devices such as isolation and scanning.
  - name: Security Events
    description: Retrieve security event data and overviews.
  - name: Risk Assessment
    description: Retrieve risk assessment summaries and detected risks.
  - name: Configurations
    description: Manage endpoint security configurations.
  - name: Licenses
    description: Retrieve endpoint security license information.
paths:
  /accounts/{accountId}/licenses:
    get:
      operationId: getLicenses
      summary: Get Licenses
      description: Retrieve endpoint security license information for the account.
      tags:
        - Licenses
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: License information.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devices:
    get:
      operationId: listDevices
      summary: List Devices
      description: >-
        Retrieve a paginated, searchable list of managed endpoint devices
        for the account. Supports OData-style query parameters.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/ODataTop'
        - $ref: '#/components/parameters/ODataSkip'
        - $ref: '#/components/parameters/ODataSearch'
        - $ref: '#/components/parameters/ODataCount'
        - $ref: '#/components/parameters/ODataOrderby'
        - name: $config
          in: query
          description: Include configuration details in the response.
          schema:
            type: string
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: List of managed devices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devicesprotectionstatus:
    get:
      operationId: getDevicesProtectionStatus
      summary: Get Devices Protection Status
      description: Retrieve protection status information for all managed devices.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/ODataTop'
        - $ref: '#/components/parameters/ODataSkip'
        - $ref: '#/components/parameters/ODataSearch'
        - $ref: '#/components/parameters/ODataCount'
        - $ref: '#/components/parameters/ODataOrderby'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Device protection status list.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/unmanageddevices:
    get:
      operationId: listUnmanagedDevices
      summary: List Unmanaged Devices
      description: Retrieve devices discovered on the network that are not yet managed.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/ODataTop'
        - $ref: '#/components/parameters/ODataSkip'
        - $ref: '#/components/parameters/ODataSearch'
        - $ref: '#/components/parameters/ODataCount'
        - $ref: '#/components/parameters/ODataOrderby'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: List of unmanaged devices.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devices/isolation:
    post:
      operationId: isolateDevices
      summary: Isolate Devices
      description: >-
        Isolate specified devices from network communication, optionally allowing
        specific programs and displaying a customized alert message.
      tags:
        - Device Actions
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IsolationRequest'
      responses:
        '200':
          description: Isolation initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devices/noisolation:
    post:
      operationId: removeDeviceIsolation
      summary: Remove Device Isolation
      description: Remove network isolation from previously isolated devices.
      tags:
        - Device Actions
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceIdsRequest'
      responses:
        '200':
          description: Isolation removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devices/uninstall:
    post:
      operationId: uninstallDeviceProtection
      summary: Uninstall Device Protection
      description: Uninstall WatchGuard endpoint protection from specified devices.
      tags:
        - Device Actions
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceIdsRequest'
      responses:
        '200':
          description: Uninstall initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/devices/action:
    post:
      operationId: performDeviceAction
      summary: Perform Device Action
      description: Initiate a device action such as reboot on specified devices.
      tags:
        - Device Actions
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceActionRequest'
      responses:
        '200':
          description: Device action initiated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/immediatescan:
    post:
      operationId: startImmediateScan
      summary: Start Immediate Scan
      description: Initiate an immediate security scan task on specified devices.
      tags:
        - Device Actions
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImmediateScanRequest'
      responses:
        '200':
          description: Immediate scan started.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/securityeventcounters/{type}:
    get:
      operationId: getSecurityEventCounters
      summary: Get Security Event Counters
      description: Retrieve counts of security events by type for the account.
      tags:
        - Security Events
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: type
          in: path
          required: true
          description: Bitmask value specifying the event types to retrieve.
          schema:
            type: integer
        - name: filter
          in: query
          schema:
            type: string
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Security event counters.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/securityevents/{type}/export/{period}:
    get:
      operationId: exportSecurityEvents
      summary: Export Security Events
      description: >-
        Retrieve detailed security event records for a specified type and time
        period (1 or 7 days).
      tags:
        - Security Events
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: type
          in: path
          required: true
          description: Security event type (1-19).
          schema:
            type: integer
            minimum: 1
            maximum: 19
        - name: period
          in: path
          required: true
          description: Time period in days (1 or 7).
          schema:
            type: integer
            enum: [1, 7]
        - name: hostname
          in: query
          description: Base-64 encoded hostname to filter events by device.
          schema:
            type: string
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Security event export.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/securityoverview/{period}:
    get:
      operationId: getSecurityOverview
      summary: Get Security Overview
      description: >-
        Retrieve a security overview summary for the account covering the
        specified number of days (1, 7, or 30).
      tags:
        - Security Events
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: period
          in: path
          required: true
          description: Period in days (1, 7, or 30).
          schema:
            type: integer
            enum: [1, 7, 30]
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Security overview summary.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/riskassessment/companyrisksummary:
    get:
      operationId: getCompanyRiskSummary
      summary: Get Company Risk Summary
      description: Retrieve company-wide risk summary categorized by severity level.
      tags:
        - Risk Assessment
      parameters:
        - $ref: '#/components/parameters/AccountId'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Company risk summary.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/riskassessment/detectedrisks:
    get:
      operationId: getDetectedRisks
      summary: Get Detected Risks
      description: >-
        Retrieve detected risk counts by type, with optional filtering by
        device type and operating system.
      tags:
        - Risk Assessment
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: $filter
          in: query
          description: OData filter expression supporting device type and OS filtering.
          schema:
            type: string
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Detected risks.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/managedconfigurations/{type}:
    get:
      operationId: getManagedConfigurations
      summary: Get Managed Configurations
      description: Retrieve managed endpoint security configurations by type.
      tags:
        - Configurations
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: type
          in: path
          required: true
          description: Configuration type (1-12).
          schema:
            type: integer
            minimum: 1
            maximum: 12
        - $ref: '#/components/parameters/ODataTop'
        - $ref: '#/components/parameters/ODataSkip'
        - $ref: '#/components/parameters/ODataSearch'
        - $ref: '#/components/parameters/ODataCount'
        - $ref: '#/components/parameters/ODataOrderby'
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: List of managed configurations.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{accountId}/installers:
    get:
      operationId: getInstaller
      summary: Get Installer
      description: >-
        Retrieve the download URL for an endpoint security installation package
        for a specific platform and configuration.
      tags:
        - Configurations
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: platformId
          in: query
          required: true
          description: Target platform identifier.
          schema:
            type: string
        - name: managedConfigurationId
          in: query
          required: true
          description: Configuration ID to associate with the installer.
          schema:
            type: string
        - name: useActiveDirectory
          in: query
          required: true
          description: Whether to use Active Directory for deployment.
          schema:
            type: boolean
      security:
        - bearerAuth: []
          apiKeyAuth: []
      responses:
        '200':
          description: Installer download URL.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token from the WatchGuard Authentication API.
    apiKeyAuth:
      type: apiKey
      in: header
      name: WatchGuard-API-Key
      description: API key from the WatchGuard Cloud Managed Access page.
  parameters:
    AccountId:
      name: accountId
      in: path
      required: true
      description: WatchGuard Cloud account ID.
      schema:
        type: string
    ODataTop:
      name: $top
      in: query
      description: Number of records to return (max 3000).
      schema:
        type: integer
        maximum: 3000
    ODataSkip:
      name: $skip
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
    ODataSearch:
      name: $search
      in: query
      description: Text search across supported fields.
      schema:
        type: string
    ODataCount:
      name: $count
      in: query
      description: Include total count in response.
      schema:
        type: boolean
    ODataOrderby:
      name: $orderby
      in: query
      description: Sort results (e.g., hostname+asc).
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized — invalid or expired access token or API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    DeviceList:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        count:
          type: integer
    Device:
      type: object
      description: An endpoint device managed by WatchGuard Endpoint Security.
      properties:
        deviceId:
          type: string
        hostname:
          type: string
        ipAddress:
          type: string
        operatingSystem:
          type: string
        agentVersion:
          type: string
        protectionStatus:
          type: string
          enum: [Protected, AtRisk, Unprotected]
        lastSeen:
          type: string
          format: date-time
    DeviceIdsRequest:
      type: object
      properties:
        device_ids:
          type: array
          items:
            type: string
          description: List of device IDs to perform the action on.
    IsolationRequest:
      type: object
      properties:
        device_ids:
          type: array
          items:
            type: string
        exclusion_programs:
          type: array
          items:
            type: string
          description: Programs allowed to communicate during isolation.
        customized_message:
          type: string
          description: Message displayed to users on isolated devices.
        hide_customized_alert:
          type: boolean
    DeviceActionRequest:
      type: object
      properties:
        device_ids:
          type: array
          items:
            type: string
        action_type:
          type: string
          description: Type of action to perform (e.g., reboot).
        count_down_type:
          type: string
    ImmediateScanRequest:
      type: object
      properties:
        device_ids:
          type: array
          items:
            type: string
        task_name:
          type: string
        task_description:
          type: string
        scan_scope:
          type: string
          description: Scope of the scan (full, quick, custom).
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string