openapi: 3.0.1
info:
  title: WatchGuard NDR Smart Alerts API
  description: REST API to manage WatchGuard NDR Smart Alerts.
  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}/smartalerts/{smartAlertId}:
    get:
      tags:
        - Get Smart Alert
      summary: Retrieves a Smart Alert.
      description: Retrieves details of a Smart Alert specified by a Smart Alert
        ID.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/smartAlertId'
        - $ref: '#/components/parameters/tenantName'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/smartAlertResponse'
        default:
          description: Error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v2/accounts/{accountId}/smartalerts/{smartAlertId}/close:
    put:
      tags:
        - Close Smart Alert
      summary: Closes a Smart Alert.
      description: Closes a Smart Alert specified by a Smart Alert ID. You can 
        also specify the reason to close the Smart Alert.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/smartAlertId'
        - $ref: '#/components/parameters/tenantName'
      requestBody:
        description: Request body to close a Smart Alert.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/closeSmartAlertRequest'
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/closeSmartAlertResponse'
        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
    smartAlertId:
      name: smartAlertId
      in: path
      description: Specifies the Smart Alert ID.
      required: true
      schema:
        type: string
      example: 
        1756794600000%7C%7Cf81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca%7C%7Cint_to_int_PRA
    tenantName:
      name: tenantName
      in: query
      required: true
      description: Specifies the WatchGuard Cloud account name for the target 
        account.
      schema:
        type: string
      example: WGC-1-123abc456 or ACC-1234567

  schemas:
    checkHealth:
      type: object
      description: Health check response.
      properties:
        healthy:
          type: boolean
          description: Indicates whether the service is operational.
          default: false
          example: true
    closeSmartAlertResponse:
      type: object
      description: Smart Alert closure response.
      properties:
        statusMessage:
          type: string
          example: Success
    smartAlertResponse:
      type: object
      description: Smart Alert response.
      properties:
        data:
          type: array
          description: Lists the Smart Alerts.
          items:
            $ref: '#/components/schemas/smartAlert'
    smartAlert:
      type: object
      description: Smart Alert object.
      properties:
        smartAlertId:
          type: string
          description: Unique identifier of the Smart Alert.
          example: 
            1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA
        name:
          type: string
          description: Specifies the name of the Smart Alert.
          example: Probing or Reconnaissance Activity
        siteId:
          type: integer
          format: int64
          description: Unique site identifier.
          example: 74
        siteName:
          type: string
          description: WatchGuard Cloud Account ID for the site.
          example: WGC-1-123abc456 or ACC-1234567
        summary:
          type: string
          description: Summary of the Smart Alert.
          example: The following behaviors suggest that host 10.0.1.2 is 
            conducting a network reconnaissance activity.
        majorActorDisplayName:
          type: array
          items:
            type: string
            example: 10.0.1.2
          description: List of major actors.
        startTime:
          type: integer
          format: int64
          description: Specifies the start time of the Smart Alert in Unix epoch
            time format.
          example: 1756794600000
        endTime:
          type: integer
          format: int64
          description: Specifies the end time of the Smart Alert in Unix epoch 
            time format.
          example: 1756796400000
        confidenceLevel:
          type: integer
          format: int32
          description: Specifies the confidence level of the Smart Alert.
          example: 100
        aocState:
          type: string
          description: Indicates the state of the Smart Alert.
          example: Closed
        property1:
          type: string
          description: Specifies dynamic behavior summary details.
        property2:
          type: string
          description: Specifies dynamic behavior summary details.
        property3:
          type: string
          description: Specifies dynamic behavior summary details.
        behaviorKeyFeatures:
          uniqueItems: true
          type: array
          items:
            type: string
            example: 
              INT_INT_HORIZONTAL_PORT_SCAN_NG.MAJOR_ASSETS_SCANNED_NONE_HIGH
          description: Lists the key behavior features of the Smart Alert.
    closeSmartAlertRequest:
      type: object
      properties:
        includeSimilar:
          type: boolean
          description: Indicates whether to include similar Smart Alerts.
          example: true
        reasonForClose:
          type: string
          enum:
            - ABNORMAL_UNAUTHORIZED
            - ABNORMAL_AUTHORIZED
            - NORMAL
            - OTHER
          description: Reason for closing the Smart Alert.
          example: NORMAL
        reasonForAuthorizedAbnormal:
          type: string
          enum:
            - PENETRATION_TESTING
            - SCANNING_APPLICATION
            - AD_HOC_TESTING
            - OTHER
          description: Specifies the reason to close the Smart Alert. Required 
            when `reasonForClose` is `ABNORMAL_AUTHORIZED`.
          example: PENETRATION_TESTING
        reasonForUnauthorizedAbnormal:
          type: string
          enum:
            - KNOWN_THREAT
            - UNKNOWN_THREAT
            - MISCONFIG
            - OTHER
          description: Specifies the reason to close the Smart Alert. Required 
            when `reasonForClose` is `ABNORMAL_UNAUTHORIZED`.
          example: KNOWN_THREAT
        allowInFuture:
          type: string
          enum:
            - AUTHORIZED
            - AUTHORIZED_ONCE
          description: Specifies whether similar activity is allowed in the 
            future.
          example: AUTHORIZED
        authorizedActivities:
          type: array
          items:
            type: string
            enum:
              - AUTHORIZED_TIMES_FREQUENCIES
              - AUTHORIZED_ACTORS
          description: Lists the activities to allow in the future when 
            `allowInFuture` is `AUTHORIZED` or `AUTHORIZED_ONCE`.
          example: [AUTHORIZED_TIMES_FREQUENCIES]
        falsePositive:
          type: boolean
          description: Indicates whether the Smart Alert is a false positive.
          example: true
        reasonForIncorrectInterpretation:
          type: array
          items:
            type: string
          description: Lists the key features used to determine that the Smart 
            Alert is not a threat.
          example: [
                INT_INT_HORIZONTAL_PORT_SCAN_NG.MAJOR_ASSETS_SCANNED_NONE_HIGH]
        otherReasonForClose:
          type: string
          enum:
            - UI_NOT_INTERESTING
            - UI_NOT_CLEAR
            - UI_NOT_HELPFUL
            - OTHER
          description: Specifies the subtype of the close reason when 
            `reasonForClose` is `OTHER`.
          example: UI_NOT_INTERESTING
        additionalInformation:
          type: string
          description: Specifies additional information about the Smart Alert.
          example: Any additional information regarding the Smart Alert.
        comment:
          type: string
          description: Specifies comments related to major actors, ports, or 
            other details.
          example: Any Comments related to the Smart Alert.
    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: Smart Alert with the specified ID was not found.
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the error.
          example: /v2/smartalerts/invalid-id
  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/smartalerts
    description: Prod USA Region
  - url: https://api.deu.cloud.watchguard.com/rest/watchguard-ndr/smartalerts
    description: Prod DEU region
  - url: https://api.jpn.cloud.watchguard.com/rest/watchguard-ndr/smartalerts
    description: Prod JPN region
security:
  - ApiKeyAuth: []
    BearerAuth: []
externalDocs:
  description: Additional documentation
  url: https://www.watchguard.com/help/docs/api/Content/en-US/home.html
