openapi: 3.0.1
info:
  title: ThreatSync+ Smart Alerts API
  description: REST API to manage ThreatSync+ Smart Alerts.
  version: 1.0.1
  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'

  /v1/accounts/{accountId}/smartalert/{smartAlertId}:
    get:
      tags:
        - Get Smart Alert
      summary: Retrieves a Smart Alert.
      description: Retrieves a specific Smart Alert by 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/json:
              schema:
                $ref: '#/components/schemas/errorResponse'

  /v1/accounts/{accountId}/smartalert/{smartAlertId}/close:
    put:
      tags:
        - Close Smart Alert
      summary: Closes a Smart Alert.
      description: Closes the Smart Alert identified by Smart Alert ID and 
        records the reason for closure.
      parameters:
        - $ref: '#/components/parameters/smartAlertId'
        - $ref: '#/components/parameters/tenantName'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        description: Request body that specifies the reason for closing the 
          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/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
    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: tenant_name
      description: Specifies the WatchGuard Cloud Account ID of the account to 
        access.
      in: query
      required: true
      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: A list of Smart Alerts.
          items:
            $ref: '#/components/schemas/smartAlert'
    smartAlert:
      type: object
      properties:
        smartalert_id:
          type: string
          description: Unique identifier of the Smart Alert.
          example: 
            1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA
        name:
          type: string
          description: Name of the Smart Alert.
          example: Probing or Reconnaissance Activity
        site_id:
          type: integer
          format: int64
          description: Unique site identifier.
          example: 74
        site_name:
          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.
        major_actor_display_name:
          type: array
          items:
            type: string
            example: 10.0.1.2
          description: List of major actors.
        starttime:
          type: integer
          format: int64
          description: Start time of the alert.
          example: 1756794600000
        endtime:
          type: integer
          format: int64
          description: End time of the alert.
          example: 1756796400000
        confidence_level:
          type: integer
          format: int32
          description: Confidence level of the alert.
          example: 100
        aoc_state:
          type: string
          description: State of the Smart Alert.
          example: Closed
        property1:
          type: string
          description: Dynamic behavior summary details.
        property2:
          type: string
          description: Dynamic behavior summary details.
        property3:
          type: string
          description: 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: Key behavior features of the Smart Alert.
    closeSmartAlertRequest:
      type: object
      properties:
        includeSimilar:
          type: boolean
          description: Indicates whether similar Smart Alerts should be 
            included.
          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: Required when reasonForClose is ABNORMAL_AUTHORIZED.
          example: PENETRATION_TESTING
        reasonForUnauthorizedAbnormal:
          type: string
          enum:
            - KNOWN_THREAT
            - UNKNOWN_THREAT
            - MISCONFIG
            - OTHER
          description: 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: Activities allowed in the future when allowInFuture is 
            true.
          example: [AUTHORIZED_TIMES_FREQUENCIES]
        falsePositive:
          type: boolean
          description: Indicates whether the Smart Alert was marked as a false 
            positive.
          example: true
        reasonForIncorrectInterpretation:
          type: array
          items:
            type: string
          description: Key features used to determine the alert was 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: Subtype when reasonForClose is OTHER.
          example: UI_NOT_INTERESTING
        additionalInformation:
          type: string
          description: Additional information about the Smart Alert.
          example: Any additional information regarding the Smart Alert.
        comment:
          type: string
          description: Comments related to major actors, ports, or other 
            details.
          example: Any Comments related to the Smart Alert.

    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: Error message description.
                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/threatsyncplus/smartalerts
    description: Prod USA Region
  - url: https://api.deu.cloud.watchguard.com/rest/threatsyncplus/smartalerts
    description: Prod DEU region
  - url: https://api.jpn.cloud.watchguard.com/rest/threatsyncplus/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
