openapi: 3.0.1
info:
  title: WatchGuard NDR Assets API
  description: REST API to manage WatchGuard NDR assets.
  version: 2.0.0
  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: Performs a health check.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkHealth'

  /v2/accounts/{accountId}/assets/{assetId}:
    get:
      tags:
        - Get Asset by ID
      summary: Retrieves the specified asset.
      description: Retrieves details for an asset specified by asset ID.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/tenantName'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    put:
      tags:
        - Update Asset
      summary: Updates the specified asset.
      description: Updates an asset detail specified by asset ID.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/tenantName'
      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/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    delete:
      tags:
        - Delete Asset
      summary: Deletes the specified asset.
      description: Deletes an asset specified by asset ID.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/assetId'
        - $ref: '#/components/parameters/tenantName'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        default:
          description: Error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v2/accounts/{accountId}/assets:
    post:
      tags:
        - Create Asset
      summary: Creates an asset.
      description: Creates an asset.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/tenantName'
      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/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    get:
      tags:
        - Get Assets
      summary: Retrieves a list of assets.
      description: >-
        Retrieves a list of all the assets for the specified tenant. To filter the
        list, you can specify the *field* and *value* parameters.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/field'
        - $ref: '#/components/parameters/value'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: >-
            A list of matching assets.
            For exact matches (for example, `addresses`, `assetInformationSources`,
            `roles`), with no results, the API returns a 404 status.
            For partial matches (for example, `name`, `deviceType`), the API returns
            a 200 status with `meta.dataTotalCount` set to zero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assetApiResponse'
        '400':
          description: A filter `value` was provided without `field`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: >-
            No assets matched an exact-match filter, or `field` was provided without
            `value`, or the `field` or `value` is not valid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Error response.
          content:
            application/problem+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: tenantName
      in: query
      required: true
      description: Specifies the WatchGuard Cloud account ID for the target 
        account.
      schema:
        type: string
      example: WGC-1-123abc456 or ACC-1234567
    assetId:
      name: assetId
      in: path
      required: true
      description: ID of the asset to retrieve.
      schema:
        type: string
      example: 123abc456
    field:
      name: field
      in: query
      required: false
      description: 'Specifies the asset field to filter on. Allowed fields: `name`,
        `deviceType`, `addresses`, `roles`, `assetInformationSources`, `operatingSystem`.
        If not specified, all assets are returned.'
      schema:
        type: string
        enum:
          - name
          - deviceType
          - addresses
          - roles
          - assetInformationSources
          - operatingSystem
      example: deviceType
    value:
      name: value
      in: query
      required: false
      description: Specifies the filter value for the *field*. Required when 
        *field* is specified.
      schema:
        type: string
      example: router
    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
    sort:
      name: sort
      in: query
      required: false
      description: 'Specifies the field to sort by. Allowed fields: `name`, `description`,
        `deviceType`, `importance`, `firstSeen`, `lastSeen`, `smartAlertCount`, `threatScore`.'
      schema:
        type: string
        enum:
          - name
          - description
          - deviceType
          - importance
          - firstSeen
          - lastSeen
          - smartAlertCount
          - threatScore
      example: name
    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

  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.
          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]
        deviceType:
          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
        - deviceType
        - 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: Specifies the address type 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: Specifies 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: Specifies metadata for the request.
          properties:
            dataTotalCount:
              type: integer
              example: 581
        nextPageUri:
          type: string
          description: Specifies the URI to retrieve the next page of results, 
            if available.
          example: 
            /v2/assets?tenantName=WGC-1-123abc456&field=deviceType&value=router&offset=10&size=20
        previousPageUri:
          type: string
          description: Specifies the URI to retrieve the previous page of 
            results, if available.
          example: 
            /v2/assets?tenantName=WGC-1-123abc456&field=name&value=server&offset=0&size=20
    assetResponse:
      type: object
      description: Asset object.
      properties:
        name:
          type: string
          description: Specifies the name or identifier of the asset.
          example: 203.0.113.101
        description:
          type: string
          description: Specifies the 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: 203.0.113.80}]
        roles:
          type: array
          description: Lists the roles associated with the asset.
          items:
            $ref: '#/components/schemas/roleType'
          example: [DHCP Server, DNS Server]
        threatScore:
          type: integer
          description: Specifies the threat score for the asset.
          example: 25
        isActive:
          type: boolean
          description: Indicates whether the asset is active.
          example: true
        deviceType:
          $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'
        assetInformationSources:
          type: array
          description: Lists the sources that initiate creation of the asset.
          items:
            $ref: '#/components/schemas/assetInformationSources'
          example: [USER]
        firstSeen:
          description: Unix epoch time in milliseconds when the system first 
            detects the asset.
          type: integer
          example: 1759887000000
        lastSeen:
          description: Unix epoch time in milliseconds when the system last 
            detects the asset.
          type: integer
          example: 1759887000000
        smartAlertCount:
          description: Specifies the number of Smart Alerts received on the 
            asset.
          type: integer
          example: 0
        operatingSystem:
          description: Operating system information for the asset.
          type: string
          example: Windows
        state:
          description: Indicates whether bidirectional traffic validates the 
            asset.
          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
      required:
        - type
      properties:
        type:
          type: string
          description: An absolute URI that identifies the type of error.
          default: about:blank
        title:
          type: string
          description: A descriptive title for the error.
        status:
          type: integer
          description: The HTTP status code that the server generates.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 404
        detail:
          type: string
          description: A description of the error.
          example: Asset field deviceType requires a value.
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the error.
          example: /v2/assets
  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
