openapi: 3.1.0
info:
  title: ThingsBoard Admin admin-controller alarm-comment-controller API
  description: 'ThingsBoard Admin API — subset of the ThingsBoard REST API (open-source IoT platform). Covers: Admin, Audit Log, Event, Usage Info, Queue, Queue Stats, Mail Config Template, Qr Code Settings, Job.'
  version: 4.3.0.3DEMO
  contact:
    name: ThingsBoard team
    url: https://thingsboard.io
    email: info@thingsboard.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://demo.thingsboard.io
  description: ThingsBoard Live Demo
- url: http://localhost:8080
  description: Local ThingsBoard server
tags:
- name: alarm-comment-controller
  description: Alarm Comment
paths:
  /api/alarm/{alarmId}/comment:
    get:
      tags:
      - alarm-comment-controller
      summary: Get Alarm Comments (getAlarmComments)
      description: "Returns a page of alarm comments for specified alarm. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
      operationId: getAlarmComments
      parameters:
      - name: alarmId
        in: path
        description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      - name: pageSize
        in: query
        description: Maximum amount of entities in a one page
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Sequence number of page starting from 0
        required: true
        schema:
          type: integer
          format: int32
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
          enum:
          - createdTime
          - id
      - name: sortOrder
        in: query
        description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDataAlarmCommentInfo'
    post:
      tags:
      - alarm-comment-controller
      summary: Create or Update Alarm Comment
      description: "Creates or Updates the Alarm Comment. When creating comment, platform generates Alarm Comment Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). The newly created Alarm Comment id will be present in the response. Specify existing Alarm Comment id to update the alarm. Referencing non-existing Alarm Comment Id will cause 'Not Found' error. \n\n To create new Alarm comment entity it is enough to specify 'comment' json element with 'text' node, for example: {\"comment\": { \"text\": \"my comment\"}}. \n\n If comment type is not specified the default value 'OTHER' will be saved. If 'alarmId' or 'userId' specified in body it will be ignored.\n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
      operationId: saveAlarmComment
      parameters:
      - name: alarmId
        in: path
        description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      requestBody:
        description: A JSON value representing the comment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlarmComment'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlarmComment'
  /api/alarm/{alarmId}/comment/{commentId}:
    delete:
      tags:
      - alarm-comment-controller
      summary: Delete Alarm Comment (deleteAlarmComment)
      description: 'Deletes the Alarm comment. Referencing non-existing Alarm comment Id will cause an error.


        Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
      operationId: deleteAlarmComment
      parameters:
      - name: alarmId
        in: path
        description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      - name: commentId
        in: path
        description: A string value representing the alarm comment id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
components:
  schemas:
    AlarmId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - ALARM
          example: ALARM
      required:
      - entityType
      - id
    JsonNode:
      description: A value representing the any type (object or primitive)
      examples:
      - {}
    AlarmComment:
      type: object
      properties:
        alarmId:
          $ref: '#/components/schemas/AlarmId'
          description: JSON object with Alarm id.
          readOnly: true
        userId:
          $ref: '#/components/schemas/UserId'
          description: JSON object with User id.
          readOnly: true
        type:
          type: string
          description: Defines origination of comment. System type means comment was created by TB. OTHER type means comment was created by user.
          enum:
          - SYSTEM
          - OTHER
          example: SYSTEM/OTHER
          readOnly: true
        comment:
          $ref: '#/components/schemas/JsonNode'
          description: JSON object with text of comment.
        id:
          $ref: '#/components/schemas/AlarmCommentId'
          description: JSON object with the alarm comment Id. Specify this field to update the alarm comment. Referencing non-existing alarm Id will cause error. Omit this field to create new alarm.
          readOnly: true
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the alarm comment creation, in milliseconds
          example: 1634058704567
          readOnly: true
        name:
          type: string
          description: representing comment text
          example: Please take a look
          readOnly: true
    AlarmCommentInfo:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AlarmCommentId'
          description: JSON object with the alarm comment Id. Specify this field to update the alarm comment. Referencing non-existing alarm Id will cause error. Omit this field to create new alarm.
          readOnly: true
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the alarm comment creation, in milliseconds
          example: 1634058704567
          readOnly: true
        alarmId:
          $ref: '#/components/schemas/AlarmId'
          description: JSON object with Alarm id.
          readOnly: true
        userId:
          $ref: '#/components/schemas/UserId'
          description: JSON object with User id.
          readOnly: true
        type:
          type: string
          description: Defines origination of comment. System type means comment was created by TB. OTHER type means comment was created by user.
          enum:
          - SYSTEM
          - OTHER
          example: SYSTEM/OTHER
          readOnly: true
        comment:
          $ref: '#/components/schemas/JsonNode'
          description: JSON object with text of comment.
        firstName:
          type: string
          description: User first name
          example: John
        lastName:
          type: string
          description: User last name
          example: Brown
        email:
          type: string
          description: User email address
          example: johnBrown@gmail.com
        name:
          type: string
          description: representing comment text
          example: Please take a look
          readOnly: true
    UserId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - USER
          example: USER
      required:
      - entityType
      - id
    AlarmCommentId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: string
          example: 784f394c-42b6-435a-983c-b7beff2784f9
      required:
      - id
    PageDataAlarmCommentInfo:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/AlarmCommentInfo'
          readOnly: true
        totalPages:
          type: integer
          format: int32
          description: Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria
          readOnly: true
        totalElements:
          type: integer
          format: int64
          description: Total number of elements in all available pages
          readOnly: true
        hasNext:
          type: boolean
          description: '''false'' value indicates the end of the result set'
          readOnly: true
  securitySchemes:
    HTTP login form:
      type: http
      description: Enter Username / Password
      scheme: loginPassword
      bearerFormat: /api/auth/login|X-Authorization
    API key form:
      type: apiKey
      description: 'Enter the API key value with ''ApiKey'' prefix in format: **ApiKey <your_api_key_value>**


        Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**


        <br>**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.<br>

        '
      name: X-Authorization
      in: header