openapi: 3.1.0
info:
  title: WatchGuard Cloud Platform Accounts Devices API
  description: The WatchGuard Cloud Platform API provides RESTful access to WatchGuard Cloud account management, including account creation and management, authorization for managed accounts, device and license activations, asset allocations, and operator management. All endpoints require an OAuth 2.0 bearer token and a WatchGuard-API-Key header.
  version: v1
  contact:
    name: WatchGuard Support
    url: https://www.watchguard.com/help/docs/API/
servers:
- url: https://api.usa.cloud.watchguard.com/rest
  description: USA Region
- url: https://api.eu.cloud.watchguard.com/rest
  description: EU Region
- url: https://api.apac.cloud.watchguard.com/rest
  description: APAC Region
tags:
- name: Devices
  description: Manage and query endpoint devices.
paths:
  /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'
components:
  parameters:
    ODataOrderby:
      name: $orderby
      in: query
      description: Sort results (e.g., hostname+asc).
      schema:
        type: string
    ODataSearch:
      name: $search
      in: query
      description: Text search across supported fields.
      schema:
        type: string
    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
    ODataCount:
      name: $count
      in: query
      description: Include total count in response.
      schema:
        type: boolean
    ODataSkip:
      name: $skip
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Unauthorized — invalid or expired access token or API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    DeviceList:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        count:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained from the WatchGuard Authentication API.
    apiKeyAuth:
      type: apiKey
      in: header
      name: WatchGuard-API-Key
      description: API key from the WatchGuard Cloud Managed Access page.