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

    '
  title: Attachment Ticket 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: Ticket
paths:
  /api/v1/organizations/{organizationUuid}/tickets:
    get:
      summary: List tickets for an organization
      description: Retrieve a paginated list of tickets for a specific organization
      operationId: listTickets
      security:
      - BearerAuth: []
      tags:
      - Ticket
      parameters:
      - $ref: '#/components/parameters/OrganizationUuid'
      - $ref: '#/components/parameters/Status'
      - $ref: '#/components/parameters/AssigneeByEmail'
      - $ref: '#/components/parameters/AssigneeByFirstName'
      - $ref: '#/components/parameters/AssigneeByLastName'
      - $ref: '#/components/parameters/UpdatedBefore'
      - $ref: '#/components/parameters/UpdatedAfter'
      - $ref: '#/components/parameters/CreatedBefore'
      - $ref: '#/components/parameters/CreatedAfter'
      - $ref: '#/components/parameters/Priority'
      - $ref: '#/components/parameters/Type'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/IncludeComments'
      responses:
        '200':
          $ref: '#/components/responses/PaginatedListTickets'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/organizations/{organizationUuid}/tickets/{ticketId}:
    get:
      summary: Get a ticket by ID
      description: Retrieve detailed information about a specific ticket
      operationId: getTicketById
      security:
      - BearerAuth: []
      tags:
      - Ticket
      parameters:
      - $ref: '#/components/parameters/OrganizationUuid'
      - $ref: '#/components/parameters/TicketId'
      - $ref: '#/components/parameters/IncludeComments'
      responses:
        '200':
          $ref: '#/components/responses/TicketResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/organizations/{organizationUuid}/tickets/{ticketId}/close:
    post:
      summary: Close a ticket
      description: Close a ticket with an optional comment
      operationId: closeTicket
      security:
      - BearerAuth: []
      tags:
      - Ticket
      parameters:
      - $ref: '#/components/parameters/OrganizationUuid'
      - $ref: '#/components/parameters/TicketId'
      requestBody:
        $ref: '#/components/requestBodies/CloseTicketRequest'
      responses:
        '200':
          $ref: '#/components/responses/CloseTicketResponse'
        '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:
  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.
    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.
    TicketResponse:
      description: Ticket details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ticket'
          examples:
            success:
              $ref: '#/components/examples/TicketOpenExample'
    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.
    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.
    PaginatedListTickets:
      description: A paginated list of tickets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedListTickets'
          examples:
            success:
              $ref: '#/components/examples/TicketListExample'
    CloseTicketResponse:
      description: Ticket successfully closed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ticket'
          examples:
            closedTicket:
              $ref: '#/components/examples/TicketClosedExample'
    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.
  parameters:
    Offset:
      in: query
      name: offset
      description: Number of items to skip before starting to return results
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 100000
      examples:
        offset:
          value: 0
    Type:
      in: query
      name: type
      description: Filter by ticket type(s). Provide single value or comma-separated list.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TicketType'
        uniqueItems: true
        minItems: 1
        maxItems: 10
      style: form
      explode: false
      examples:
        type:
          value:
          - INCIDENT
          - PROBLEM
    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
    UpdatedBefore:
      in: query
      name: updatedBefore
      description: Filter tickets that were last updated before this timestamp (ISO 8601, UTC)
      schema:
        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
      examples:
        timestamp:
          value: '2026-03-04T14:00:00Z'
    Status:
      in: query
      name: status
      description: Filter by ticket status(es). Provide single value or comma-separated list.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TicketStatus'
        uniqueItems: true
        minItems: 1
        maxItems: 10
      style: form
      explode: false
      examples:
        status:
          value:
          - OPEN
          - PENDING
    AssigneeByEmail:
      in: query
      name: assigneeByEmail
      description: Filter by assignee email(s). Provide single email or comma-separated list.
      schema:
        type: array
        items:
          type: string
          format: email
          pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
          minLength: 3
          maxLength: 254
        uniqueItems: true
        minItems: 1
        maxItems: 50
      style: form
      explode: false
      examples:
        email:
          value:
          - agent@example.com
          - agent2@example.com
    Limit:
      in: query
      name: limit
      description: Maximum number of items to return
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
      examples:
        limit:
          value: 20
    Priority:
      in: query
      name: priority
      description: Filter by priority level(s). Provide single value or comma-separated list.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Priority'
        uniqueItems: true
        minItems: 1
        maxItems: 4
      style: form
      explode: false
      examples:
        priority:
          value:
          - HIGH
          - URGENT
    CreatedBefore:
      in: query
      name: createdBefore
      description: Filter tickets that were created before this timestamp (ISO 8601, UTC)
      schema:
        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
      examples:
        timestamp:
          value: '2026-03-04T23:59:59Z'
    CreatedAfter:
      in: query
      name: createdAfter
      description: Filter tickets that were created after this timestamp (ISO 8601, UTC)
      schema:
        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
      examples:
        timestamp:
          value: '2026-02-01T00:00:00Z'
    IncludeComments:
      in: query
      name: includeComments
      description: Whether to include comments & attachments in the response
      schema:
        type: boolean
        default: false
      examples:
        includeComments:
          value: false
    UpdatedAfter:
      in: query
      name: updatedAfter
      description: Filter tickets that were last updated after this timestamp (ISO 8601, UTC)
      schema:
        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
      examples:
        timestamp:
          value: '2026-03-01T00:00:00Z'
    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
    AssigneeByLastName:
      in: query
      name: assigneeByLastName
      description: Filter by assignee last name(s). Provide single name or comma-separated list.
      schema:
        type: array
        items:
          type: string
          pattern: ^[a-zA-Z\s\-\.,\']+$
          minLength: 1
          maxLength: 100
        uniqueItems: true
        minItems: 1
        maxItems: 50
      style: form
      explode: false
      examples:
        lastName:
          value:
          - Doe
          - Smith
    AssigneeByFirstName:
      in: query
      name: assigneeByFirstName
      description: Filter by assignee first name(s). Provide single name or comma-separated list.
      schema:
        type: array
        items:
          type: string
          pattern: ^[a-zA-Z\s\-\.,\']+$
          minLength: 1
          maxLength: 100
        uniqueItems: true
        minItems: 1
        maxItems: 50
      style: form
      explode: false
      examples:
        firstName:
          value:
          - John
          - Jane
  schemas:
    CloseTicketRequest:
      type: object
      description: Request body for closing a ticket
      properties:
        comment:
          type: string
          minLength: 1
          maxLength: 65535
          pattern: ^[\s\S]*$
          description: Optional comment to add when closing the ticket (maximum 65535 characters)
    Ticket:
      type: object
      description: Represents a support ticket
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: Unique identifier for the ticket
        title:
          type: string
          description: Brief summary of the ticket issue
          pattern: ^[\s\S]*$
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: Detailed description of the ticket issue
          pattern: ^[\s\S]*$
          minLength: 1
          maxLength: 65535
        organizationUuid:
          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: UUID of the organization this ticket belongs to
        status:
          $ref: '#/components/schemas/TicketStatus'
          description: Current status of the ticket
        assignee:
          $ref: '#/components/schemas/User'
          description: The assignee maps to the Assigned To field in the Arctic Wolf Unified Portal.
        priority:
          $ref: '#/components/schemas/Priority'
          description: Priority level of the ticket
        type:
          $ref: '#/components/schemas/TicketType'
          description: Type of the ticket
        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 ticket was created (ISO 8601, UTC)
        updatedAt:
          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 ticket was last updated (ISO 8601, UTC)
        commentCount:
          type: integer
          minimum: 0
          maximum: 100000
          description: Total number of comments on the ticket (includes all comments)
        attachmentCount:
          type: integer
          minimum: 0
          maximum: 1000
          description: Total number of non-deleted attachments on the ticket
        comments:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
          minItems: 0
          maxItems: 10000
          description: List of comments (included if requested)
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          minItems: 0
          maxItems: 1000
          description: List of attachments
    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
    Meta:
      type: object
      description: Pagination metadata for list responses
      required:
      - offset
      - limit
      - total
      properties:
        offset:
          type: integer
          minimum: 0
          maximum: 100000
          description: Number of items skipped before starting to return results
        limit:
          type: integer
          minimum: 1
          maximum: 1000
          description: Maximum number of items returned
        total:
          type: integer
          minimum: 0
          maximum: 10000000
          description: Total number of items available
    TicketStatus:
      type: string
      description: 'Ticket status mapping with Unified Portal: OPEN, NEW, HOLD -> With Arctic Wolf; PENDING -> With Customer; CLOSED -> Closed; OPEN, NEW, HOLD, PENDING -> Open.'
      enum:
      - OPEN
      - NEW
      - PENDING
      - HOLD
      - CLOSED
      minLength: 3
      maxLength: 7
    TicketType:
      type: string
      description: Type of ticket
      enum:
      - QUESTION
      - INCIDENT
      - PROBLEM
      - TASK
      minLength: 4
      maxLength: 8
    PaginatedListTickets:
      type: object
      description: Paginated list of tickets
      required:
      - results
      - meta
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Ticket'
          minItems: 0
          maxItems: 1000
          description: Array of ticket objects
        meta:
          $ref: '#/components/schemas/Meta'
          description: Pagination metadata
    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
    Attachment:
      type: object
      description: Represents a file attachment on a ticket or comment
      required:
      - id
      - deleted
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: Unique identifier for the attachment
        commentId:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: ID of the comment this attachment belongs to
        deleted:
          type: boolean
          description: Whether the attachment has been deleted. Deleted attachments are returned for audit purposes but cannot be downloaded.
        filename:
          type: string
          description: Name of the attached file
          pattern: ^[^\\/:*?<>|]*$
          minLength: 1
          maxLength: 255
        contentType:
          type: string
          description: MIME type of the attached file
          pattern: ^[a-zA-Z][a-zA-Z0-9][a-zA-Z0-9!#$&\-\^]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^]*$
          minLength: 3
          maxLength: 100
        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 attachment was created (ISO 8601, UTC)
    CommentType:
      type: string
      description: Type of comment
      enum:
      - PUBLIC
      - INTERNAL
      minLength: 6
      maxLength: 8
    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
    Priority:
      type: string
      description: Priority level for the ticket
      enum:
      - LOW
      - NORMAL
      - HIGH
      - URGENT
      minLength: 3
      maxLength: 6
  examples:
    TicketListExample:
      summary: Example of a paginated ticket list
      value:
        results:
        - id: 12345
          title: Cannot log in
          description: User reports login failure
          organizationUuid: 550e8400-e29b-41d4-a716-446655440000
          status: OPEN
          assignee:
            firstName: John
            lastName: Doe
            email: agent@example.com
          priority: HIGH
          type: INCIDENT
          createdAt: '2025-07-31T10:00:00Z'
          updatedAt: '2025-08-01T12:00:00Z'
          commentCount: 2
          attachmentCount: 1
          comments:
          - id: 90001
            body: Investigating the issue.
            author:
              firstName: John
              lastName: Doe
              email: agent@example.com
            createdAt: '2025-08-01T11:00:00Z'
            type: PUBLIC
          attachments:
          - id: 70001
            commentId: 90001
            deleted: false
            filename: auth-log.txt
            contentType: text/plain
            createdAt: '2025-08-01T11:01:00Z'
        meta:
          offset: 0
          limit: 20
          total: 1
    TicketClosedExample:
      summary: Example of a closed ticket
      value:
        id: 12345
        title: Cannot log in
        description: User reports login failure
        organizationUuid: 550e8400-e29b-41d4-a716-446655440000
        status: CLOSED
        assignee:
          firstName: John
          lastName: Doe
          email: agent@example.com
        priority: HIGH
        type: INCIDENT
        createdAt: '2025-07-31T10:00:00Z'
        updatedAt: '2025-08-01T12:30:00Z'
        commentCount: 3
        attachmentCount: 0
    TicketOpenExample:
      summary: Example of an open ticket
      value:
        id: 12345
        title: Cannot log in
        description: User reports login failure
        organizationUuid: 550e8400-e29b-41d4-a716-446655440000
        status: OPEN
        assignee:
          firstName: John
          lastName: Doe
          email: agent@example.com
        priority: HIGH
        type: INCIDENT
        createdAt: '2025-07-31T10:00:00Z'
        updatedAt: '2025-08-01T12:00:00Z'
        commentCount: 2
        attachmentCount: 0
  requestBodies:
    CloseTicketRequest:
      description: Comment for closing a ticket
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CloseTicketRequest'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT