openapi: 3.1.0
info:
  title: Comments API
  description: REST API for managing comments on objects in the platform
  contact:
    name: ILM
    url: https://www.otilm.com
    email: ilm@omnitrust.com
  license:
    name: "Apache License, Version 2.0"
    url: https://github.com/OmniTrustILM/interface-documentation/blob/main/LICENSE.md
  version: 2.20.0
  x-logo:
    url: images/ilm-logo.svg
externalDocs:
  description: ILM Documentation
  url: https://docs.otilm.com
servers:
- url: https://demo.otilm.com/api
  description: ILM Demo server
tags:
- name: Comments
  description: Comments API
paths:
  /v1/comments/{resource}/{objectUuid}:
    get:
      tags:
      - Comments
      summary: List comment threads for an object
      description: "Pages over thread roots in creation order, oldest first unless\
        \ the direction says otherwise; each root carries its reply count. Replies\
        \ are paged separately. Pass anchorUuid, a thread root, to open the page holding\
        \ that thread in the requested direction, in place of the requested page;\
        \ an anchor that no longer exists or is not a root of this object leaves the\
        \ requested page unchanged. A reply is anchored on the replies listing."
      operationId: listComments
      parameters:
      - name: resource
        in: path
        description: Resource
        required: true
        schema:
          $ref: "#/components/schemas/Resource"
      - name: objectUuid
        in: path
        description: Object UUID
        required: true
        schema:
          type: string
          format: uuid
      - name: anchorUuid
        in: query
        description: Thread root whose page replaces the requested one; ignored when
          it no longer exists or is not a root of this object
        required: false
        schema:
          type: string
          format: uuid
      - name: sortDirection
        in: query
        description: Direction of the ordering
        required: false
        schema:
          $ref: "#/components/schemas/SortDirection"
      - name: itemsPerPage
        in: query
        description: Number of entries per page
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          description: Number of entries per page
          maximum: 1000
      - name: pageNumber
        in: query
        description: Page number for the request
        required: false
        schema:
          type: integer
          format: int32
          default: 1
          description: Page number for the request
      responses:
        "200":
          description: Comment threads retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentResponseDto"
        "422":
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
    post:
      tags:
      - Comments
      summary: Post a comment or a reply on an object
      description: A request without parentUuid starts a new thread; with parentUuid
        it replies to that thread root. Threads are one level deep.
      operationId: createComment
      parameters:
      - name: resource
        in: path
        description: Resource
        required: true
        schema:
          $ref: "#/components/schemas/Resource"
      - name: objectUuid
        in: path
        description: Object UUID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentCreateRequestDto"
        required: true
      responses:
        "200":
          description: Comment created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentDto"
        "422":
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/comments/{uuid}/unresolve:
    patch:
      tags:
      - Comments
      summary: Reopen a resolved comment thread
      description: Thread roots only.
      operationId: unresolveComment
      parameters:
      - name: uuid
        in: path
        description: Comment UUID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Comment thread reopened
        "422":
          description: Unprocessable Content
          content:
            '*/*':
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/comments/{uuid}/resolve:
    patch:
      tags:
      - Comments
      summary: Resolve a comment thread
      description: Thread roots only.
      operationId: resolveComment
      parameters:
      - name: uuid
        in: path
        description: Comment UUID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Comment thread resolved
        "422":
          description: Unprocessable Content
          content:
            '*/*':
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/comments/{uuid}/replies:
    get:
      tags:
      - Comments
      summary: List replies of a comment thread
      description: "Pages over the thread root's replies in creation order, oldest\
        \ first unless the direction says otherwise. Pass anchorUuid to open the page\
        \ holding a particular reply in the requested direction, in place of the requested\
        \ page; an anchor that no longer exists or is not a reply of this thread leaves\
        \ the requested page unchanged."
      operationId: listReplies
      parameters:
      - name: uuid
        in: path
        description: Comment UUID
        required: true
        schema:
          type: string
          format: uuid
      - name: anchorUuid
        in: query
        description: Reply whose page replaces the requested one; ignored when it
          no longer exists or is not a reply of this thread
        required: false
        schema:
          type: string
          format: uuid
      - name: sortDirection
        in: query
        description: Direction of the ordering
        required: false
        schema:
          $ref: "#/components/schemas/SortDirection"
      - name: itemsPerPage
        in: query
        description: Number of entries per page
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          description: Number of entries per page
          maximum: 1000
      - name: pageNumber
        in: query
        description: Page number for the request
        required: false
        schema:
          type: integer
          format: int32
          default: 1
          description: Page number for the request
      responses:
        "200":
          description: Thread replies retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentResponseDto"
        "422":
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/comments/{uuid}:
    delete:
      tags:
      - Comments
      summary: Delete a comment
      description: Deleting a thread root that has replies also deletes the replies.
      operationId: deleteComment
      parameters:
      - name: uuid
        in: path
        description: Comment UUID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "204":
          description: Comment deleted
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
components:
  schemas:
    Resource:
      type: string
      enum:
      - NONE
      - ANY
      - dashboard
      - settings
      - auditLogs
      - credentials
      - connectors
      - attributes
      - jobs
      - proxies
      - users
      - roles
      - acmeAccounts
      - acmeProfiles
      - cboms
      - cryptoAssets
      - scepProfiles
      - cmpProfiles
      - authorities
      - raProfiles
      - certificates
      - certificateRequests
      - groups
      - complianceProfiles
      - discoveries
      - oids
      - entities
      - locations
      - tokenProfiles
      - tokens
      - keys
      - approvalProfiles
      - approvals
      - comments
      - notificationProfiles
      - notificationInstances
      - rules
      - actions
      - triggers
      - resources
      - resourceEvents
      - searchFilters
      - listViews
      - keyItems
      - platformEnums
      - notifications
      - conditions
      - executions
      - complianceRules
      - complianceGroups
      - customAttributes
      - globalMetadata
      - acmeOrders
      - acmeAuthorizations
      - acmeChallenges
      - cmpTransactions
      - endEntityProfiles
      - authenticationProviders
      - trustedCertificates
      - vaults
      - vaultProfiles
      - secrets
      - signingProfiles
      - signingRecords
      - timeQualityConfigurations
      - tspProfiles
      - tspProfileBasicCredentials
    CommentCreateRequestDto:
      type: object
      description: Request to post a comment or a reply on an object. Author identity
        and creation timestamp are populated by the server from the authenticated
        principal.
      properties:
        body:
          type: string
          description: Comment body as verbatim Markdown source
          maxLength: 65536
          minLength: 0
        parentUuid:
          type: string
          format: uuid
          description: "UUID of the thread root this comment replies to. Threads are\
            \ one level deep: the referenced comment must be a thread root on the\
            \ same object."
      required:
      - body
    ErrorMessageDto:
      type: object
      properties:
        message:
          type: string
          description: Error message detail
          examples:
          - Error message
      required:
      - message
    AuthenticationServiceExceptionDto:
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
          description: Status code of the HTTP Request
        code:
          type: string
          description: Code of the result
        message:
          type: string
          description: Exception message
      required:
      - code
      - message
      - statusCode
    CommentDto:
      type: object
      description: A comment on an object. Thread roots carry resolution state and
        a reply count; replies carry neither.
      properties:
        uuid:
          type: string
          format: uuid
          description: Comment UUID
        resource:
          $ref: "#/components/schemas/Resource"
          description: Host resource the commented object belongs to
        objectUuid:
          type: string
          format: uuid
          description: UUID of the commented object
        author:
          $ref: "#/components/schemas/NameAndUuidDto"
          description: UUID and username of the author; server-populated
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp; server-populated
        body:
          type: string
          description: Comment body as verbatim Markdown source
        resolved:
          type: boolean
          description: Whether the thread is resolved; thread roots only
        resolvedBy:
          $ref: "#/components/schemas/NameAndUuidDto"
          description: UUID and username of the resolving user; resolved thread roots
            only
        resolvedAt:
          type: string
          format: date-time
          description: Resolution timestamp; resolved thread roots only
        replyCount:
          type: integer
          format: int64
          description: Number of replies in the thread; thread roots only. The replies
            themselves are paged separately.
      required:
      - author
      - body
      - createdAt
      - objectUuid
      - resource
      - uuid
    NameAndUuidDto:
      type: object
      properties:
        uuid:
          type: string
          description: Object identifier
          examples:
          - 7b55ge1c-844f-11dc-a8a3-0242ac120002
        name:
          type: string
          description: Object Name
          examples:
          - Name
      required:
      - name
      - uuid
    SortDirection:
      type: string
      default: asc
      description: Direction of the ordering
      enum:
      - asc
      - desc
    CommentResponseDto:
      type: object
      properties:
        itemsPerPage:
          type: integer
          format: int32
          description: Number of entries per page
        pageNumber:
          type: integer
          format: int32
          description: Page number for the request
        totalPages:
          type: integer
          format: int32
          description: Number of pages available
        totalItems:
          type: integer
          format: int64
          description: Number of items available
        comments:
          type: array
          description: "Comments on the requested page: thread roots for the object\
            \ listing, replies for the thread listing"
          items:
            $ref: "#/components/schemas/CommentDto"
      required:
      - comments
      - itemsPerPage
      - pageNumber
      - totalItems
      - totalPages
  securitySchemes:
    SessionAuth:
      type: apiKey
      description: Session-based authentication with session ID stored in 'session-id'
        cookie
      name: session-id
      in: cookie
    CertificateAuth:
      type: apiKey
      description: Base64 encoded X.509 certificate passed in header
      name: ssl-client-cert
      in: header
    BearerJWTAuth:
      type: http
      scheme: Bearer
      bearerFormat: JWT