openapi: 3.0.1
info:
  title: WatchGuard NDR Assets API
  description: REST API to manage WatchGuard NDR assets.
  version: 1.0.4
  contact:
    name: API Support
    url: https://www.watchguard.com/wgrd-support/contact-support
  termsOfService: 
    https://www.watchguard.com/help/docs/api/Content/en-US/license_agreement.html?cshid=18007
paths:
  /health:
    get:
      tags:
        - Check Health
      description: Health check endpoint.
      summary: Perform health check.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkHealth'

  /v1/accounts/{accountId}/asset:
    post:
      tags:
        - Create Asset
      summary: Creates an asset.
      description: Creates an asset.
      parameters:
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        description: Request body to create an asset.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assetRequest'
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v1/accounts/{accountId}/asset/{assetId}:
    get:
      tags:
        - Get Asset by ID
      summary: Retrieves an existing asset.
      description: Retrieves a specific asset by asset ID.
      parameters:
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

    delete:
      tags:
        - Delete an asset
      summary: Delete an existing asset.
      description: Deletes an asset by its asset ID.
      parameters:
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

    put:
      tags:
        - Update an asset
      summary: Updates an existing asset.
      description: Updates an existing asset by asset ID.
      parameters:
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        description: Request body to update the asset information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assetRequest'
        required: true
      responses:
        '200':
          description: Successfully updated the asset. The response includes the
            updated asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v1/accounts/{accountId}/asset/field/{field}:
    get:
      tags:
        - Get asset by field
      summary: Retrieves assets by field.
      description: Retrieves a list of assets that match the specified field 
        value.
      parameters:
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/field'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/value'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: >
            Retrieves a list of matching assets. For exact matches (for example,
            `addresses`, `asset_information_sources`, `roles`), a 404 status is
            returned if no results are found. For partial matches (for example,
            `name`, `device_type`), the API returns a 200 status with
            `meta.dataTotalCount` set to zero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v1/accounts/{accountId}/asset/names:
    get:
      tags:
        - Get assets based on name
      summary: Retrieves assets filtered by name.
      description: Retrieves a list of asset names filtered by an optional asset
        name value.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/assetName'
      responses:
        '200':
          description: >
            Retrieves a list of assets. For partial matches on the `name` field,
            the API returns a 200 status with `meta.dataTotalCount` set to zero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

components:
  parameters:
    accountId:
      name: accountId
      in: path
      description: Specifies the WatchGuard Cloud account ID.
      required: true
      schema:
        type: string
      example: WGC-1-123abc456 or ACC-1234567
    tenantName:
      name: tenant_name
      description: Specifies the WatchGuard Cloud account name for the target 
        account.
      in: query
      required: true
      schema:
        type: string
      example: WGC-1-123abc456 or ACC-1234567
    assetId:
      name: asset_id
      in: path
      description: Specifies the CyGlass-assigned asset identifier.
      required: true
      schema:
        type: string
      example: 123abc456
    size:
      name: size
      in: query
      description: 'Specifies the number of assets to return. Default: 10. Range:
        10–5000.'
      schema:
        type: integer
      required: false
      example: 20
    offset:
      name: offset
      description: Specifies the index from which the result set starts (used 
        for pagination).
      in: query
      schema:
        type: integer
      required: false
      example: 0
    order:
      name: order
      description: 'Specifies the sort order. Default: 0 (ascending). Allowed values:
        0 (ascending), 1 (descending).'
      in: query
      schema:
        type: integer
      required: false
      example: 1
    value:
      name: value
      in: query
      description: Specifies the filter value for the field.
      schema:
        type: string
      required: true
      example: server
    assetName:
      name: value
      in: query
      required: false
      description: Specifies the asset name to search for. Supports partial or 
        full matches. If not specified, all assets are returned.
      schema:
        type: string
    sort:
      name: sort
      in: query
      schema:
        type: string
      description: 'Specifies the field to sort by. Default: `name`. Allowed fields:
        `name`, `description`, `threat_score`, `device_type`, `importance`, `first_seen`,
        `last_seen`, `smartalert_count`.'
      example: name
    field:
      name: field
      in: path
      required: true
      description: 'Specifies the asset field to query. Supported values: `name`,
        `addresses`, `asset_information_sources`, `roles`, `device_type`.'
      schema:
        type: string
      example: name

  schemas:
    checkHealth:
      type: object
      description: Health check response.
      properties:
        healthy:
          type: boolean
          description: Indicates whether the service is operational.
          default: false
          example: true
    assetRequest:
      type: object
      description: Request body to create or update an asset.
      properties:
        name:
          type: string
          description: Specifies the name or identifier of the asset.
          example: 10.5.0.33
        description:
          type: string
          description: Specifies the description of the asset.
          example: This is sample description for the asset.
        addresses:
          type: array
          description: Accepts only `IP_V4` for create and update operations. 
            Requests with other types are rejected.
          items:
            $ref: '#/components/schemas/assetAddress'
          example: [{type: IP_V4, value: 10.0.0.15}]
        roles:
          type: array
          description: Lists the roles associated with the asset.
          items:
            $ref: '#/components/schemas/roleType'
          example: [DHCP Server, DNS Server]
        device_type:
          type: array
          description: Lists the device types the asset belongs to.
          items:
            $ref: '#/components/schemas/deviceType'
          example: [Server, Printer]
        tags:
          type: array
          description: Lists the tags associated with the asset.
          items:
            type: string
          example: [server1]
        importance:
          $ref: '#/components/schemas/importance'
      required:
        - name
        - addresses
        - device_type
        - importance
    assetAddress:
      type: object
      description: Stores the asset address or identifier, including the type 
        and value.
      properties:
        type:
          $ref: '#/components/schemas/addressType'
        value:
          type: string
      example: {type: IP_V4, value: 192.168.1.10}
    importance:
      type: integer
      description: 'Specifies the asset importance. Allowed values: 1 (Very Low),
        2 (Low), 3 (Medium), 4 (High), 5 (Very High).'
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      example: 1
    addressType:
      type: string
      description: Lists the different kinds of addresses or IDs you can use for
        an asset.
      enum:
        - IP_V4
        - IP_V6
        - MAC
        - WINDOWS
        - DNS
        - AWS_AMI_ID
        - DOCKER_IMAGE_ID
        - ORGANIZATION
        - HOSTNAME
        - VPN_USERNAME
        - VPN_REMOTE_IP
        - OFFICE365_USERNAME
        - AD
      example: IP_V4
    roleType:
      type: string
      description: Defines the role or function an asset performs on the 
        network.
      enum:
        - Active Directory Server
        - DHCP Server
        - DNS Server
        - Exchange Server
        - Firewall
        - FTP Server
        - IMAP Mail Server
        - IMAP/SSL Mail Server
        - LDAP Server
        - LDAP/SSL Server
        - NFS Server
        - Oracle Database Server
        - POP3 Mail Server
        - POP3/SSL Mail Server
        - Proxy Server/Edge
        - Secure Web Server
        - Security Server
        - SMTP Mail Server
        - SMTP/SSL Mail Server
        - SQL Database Server
        - SSH Server
        - Web Server
        - Telnet server
        - Backup Server
        - WSUS Server
        - File Server
        - Remote Desktop Services
        - Domain Controller
        - SCVMM
      example: DHCP Server
    deviceType:
      type: string
      description: Specifies device type of the asset.
      enum:
        - Server
        - Printer
        - Computer
        - Router
        - Network
        - Database Server
        - Email Gateway
        - Firewall
        - Domain Controller
        - Vpn Server
        - Proxy Server
        - Application Server
        - Cluster
        - Cluster SAN Fabric
        - Access Point
        - Switch
        - Storage Device
        - Network Switch
        - Network Attached Storage
        - Wireless Access Point
        - Gateway
        - End User Computing
      example: Server
    assetApiResponse:
      description: Standard response format for asset requests.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/assetResponse'
          description: Contains a list of asset response objects.
        requestId:
          type: string
          description: Specifies unique identifier of the request.
          example: xyz
        status:
          type: integer
          description: Indicates the response status.
          example: 200
        meta:
          type: object
          description: Provides metadata for the request.
          example: {dataTotalCount: 581}
        nextPageUri:
          type: string
          description: Provides the URI to retrieve the next page of results, if
            available.
          example: /v1/asset/field/name/?tenant_name=qas19v1&value=1.&offset=10
        previousPageUri:
          type: string
          description: Provides the URI to retrieve the previous page of 
            results, if available.
          example: /v1/asset/field/name/?tenant_name=qas19v1&value=1.&offset=10
    assetResponse:
      type: object
      description: Asset object.
      properties:
        name:
          type: string
          description: Specifies the name or identifier of the asset, such as an
            IP address.
          example: 1.12.73.101
        description:
          type: string
          description: Provides a description of the asset.
          example: This is a sample description.
        id:
          type: string
          description: Represents the unique identifier of the asset.
          example: 30a3d6ca-aeee-4331-bf2f-49aa70f709aa
        addresses:
          type: array
          description: Lists the addresses associated with the asset.
          items:
            $ref: '#/components/schemas/assetAddress'
          example: [{type: IP_V4, value: 1.12.64.80}]
        roles:
          type: array
          description: Lists the roles associated with the asset.
          items:
            $ref: '#/components/schemas/roleType'
          example: [DHCP Server, DNS Server]
        threat_score:
          type: integer
          description: Indicates the threat score for the asset.
          example: 25
        is_active:
          type: boolean
          description: Indicates whether the asset is active.
          example: true
        device_type:
          $ref: '#/components/schemas/deviceType'
        tags:
          type: array
          description: Lists the tags associated with the asset.
          items:
            type: string
          example: [server1]
        importance:
          $ref: '#/components/schemas/importance'
        asset_information_sources:
          type: array
          description: Indicates the source that initiated the creation of the 
            asset.
          items:
            $ref: '#/components/schemas/assetInformationSources'
          example: [USER]
        first_seen:
          description: Unix epoch time in milliseconds when the asset was first 
            seen.
          type: integer
          example: 1759887000000
        last_seen:
          description: Unix epoch time in milliseconds when the asset was last 
            seen.
          type: integer
          example: 1759887000000
        smartalert_count:
          description: Specifies number of smart alerts received on the asset.
          type: integer
          example: 0
        operating_system:
          description: Operating system information for the asset.
          type: string
          example: Windows
        state:
          description: Indicates whether the device has been validated by 
            observing bidirectional traffic.
          type: string
          example: Confirmed
    assetInformationSources:
      type: string
      description: Indicates the source that initiated the creation of the 
        asset.
      enum:
        - DHCP_LOG
        - USER
        - VPN_LOG
        - SYSTEM
      example: USER

    errorResponse:
      type: object
      description: Error response.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              messageKey:
                type: string
                description: Error message code.
                example: API_GENERIC_NOT_FOUND
              messageText:
                type: string
                description: Human-readable error message.
                example: Not found
              params:
                type: object
                description: Request parameters that caused the error.
                additionalProperties:
                  type: string
                example:
                  tenant_name: WGC-1-123abc456 or ACC-1234567
        status:
          type: number
          description: HTTP status code.
          example: 404
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: WatchGuard-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
  - url: https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets
    description: Prod USA Region
  - url: https://api.deu.cloud.watchguard.com/rest/watchguard-ndr/assets
    description: Prod DEU region
  - url: https://api.jpn.cloud.watchguard.com/rest/watchguard-ndr/assets
    description: Prod JPN region
security:
  - ApiKeyAuth: []
    BearerAuth: []
externalDocs:
  description: Additional documentation
  url: https://www.watchguard.com/help/docs/api/Content/en-US/home.html
