openapi: 3.1.0
info:
  description: 'APIs for retrieving and closing tickets for an organization.

    '
  title: Ticket Attachment Comment API
  version: 1.0.0
servers:
- description: US001
  url: https://ticket-api.managedgw.us001-prod.arcticwolf.net
- description: US002
  url: https://ticket-api.managedgw.us002-prod.arcticwolf.net
- description: US003
  url: https://ticket-api.managedgw.us003-prod.arcticwolf.net
- description: EU001
  url: https://ticket-api.managedgw.eu001-prod.arcticwolf.net
- description: AU001
  url: https://ticket-api.managedgw.au001-prod.arcticwolf.net
- description: CA001
  url: https://ticket-api.managedgw.ca001-prod.arcticwolf.net
tags:
- name: Comment
paths:
  /api/v1/organizations/{organizationUuid}/tickets/{ticketId}/comments:
    post:
      summary: Add a comment to a ticket
      description: Add a new comment to an existing ticket
      operationId: addCommentToTicket
      security:
      - BearerAuth: []
      tags:
      - Comment
      parameters:
      - $ref: '#/components/parameters/OrganizationUuid'
      - $ref: '#/components/parameters/TicketId'
      requestBody:
        $ref: '#/components/requestBodies/AddCommentRequest'
      responses:
        '200':
          $ref: '#/components/responses/AddCommentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    User:
      type: object
      description: Represents a user (assignee or author)
      properties:
        firstName:
          type: string
          pattern: ^[a-zA-Z\s\-\.,\']*$
          minLength: 1
          maxLength: 100
          description: First name of the user
        lastName:
          type: string
          pattern: ^[a-zA-Z\s\-\.,\']*$
          minLength: 1
          maxLength: 100
          description: Last name of the user
        email:
          type: string
          format: email
          pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
          minLength: 3
          maxLength: 254
          description: Email address of the user
    CommentType:
      type: string
      description: Type of comment
      enum:
      - PUBLIC
      - INTERNAL
      minLength: 6
      maxLength: 8
    AddCommentRequest:
      type: object
      description: Request body for adding a comment to a ticket
      required:
      - body
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 65535
          pattern: ^[\s\S]*$
          description: The comment text to add (maximum 65535 characters)
          examples:
          - We are currently investigating this issue.
    Error:
      type: object
      description: Error envelope; returned when we encounter an error
      required:
      - code
      properties:
        code:
          description: Error code identifier
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          minLength: 1
          maxLength: 100
        description:
          description: Detailed error description
          type: string
          pattern: ^[\s\S]*$
          minLength: 1
          maxLength: 1000
    Comment:
      type: object
      description: Represents a comment on a ticket
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: Unique identifier for the comment
        body:
          type: string
          minLength: 1
          maxLength: 65535
          pattern: ^[\s\S]*$
          description: Comment body text (maximum 65535 characters)
        author:
          $ref: '#/components/schemas/User'
          description: User who authored the comment
        createdAt:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?([+-]\d{2}:\d{2}|Z)$
          minLength: 19
          maxLength: 29
          description: Timestamp when the comment was created (ISO 8601, UTC)
        type:
          $ref: '#/components/schemas/CommentType'
          description: Indicates whether the comment is public or internal
  responses:
    ForbiddenError:
      description: Authenticated but insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                code: forbidden
                description: Insufficient permissions to access this resource.
    AddCommentResponse:
      description: Comment successfully added to ticket
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Comment'
          examples:
            addedComment:
              $ref: '#/components/examples/CommentAddedExample'
    NotFoundError:
      description: Ticket not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              value:
                code: not_found
                description: Ticket with ID 12345 was not found.
            attachmentNotFound:
              value:
                code: not_found
                description: Attachment with ID 123 belonging to Ticket with ID 456 was not found.
    UnauthorizedError:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              value:
                code: unauthorized
                description: Invalid or expired authentication token.
    BadRequestError:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            badRequest:
              value:
                code: invalid_request
                description: The 'limit' parameter must be less than or equal to 100.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              value:
                code: internal_server_error
                description: An unexpected error occurred while processing your request.
  requestBodies:
    AddCommentRequest:
      description: Add comment to a ticket
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddCommentRequest'
  parameters:
    TicketId:
      in: path
      name: ticketId
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
        maximum: 9223372036854776000
      description: The unique identifier for the ticket
      examples:
        ticketId:
          value: 12345
    OrganizationUuid:
      in: path
      name: organizationUuid
      required: true
      schema:
        type: string
        format: uuid
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        minLength: 36
        maxLength: 36
      description: The unique identifier for the organization
      examples:
        uuid:
          value: 550e8400-e29b-41d4-a716-446655440000
  examples:
    CommentAddedExample:
      summary: Example of a comment added to a ticket
      value:
        id: 90002
        body: Thank you for reporting this issue. I've escalated it to our engineering team and will provide an update within 24 hours.
        author:
          firstName: Jane
          lastName: Smith
          email: agent@example.com
        createdAt: '2026-03-04T14:30:00Z'
        type: PUBLIC
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT