openapi: 3.0.3
info:
  title: Quiz Service API
  description: API for managing quizzes, questions, answers and statistics
  version: 2.0.0
paths:
  /account/get:
    get:
      tags: [Account]
      summary: Get the current account details
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/create:
    post:
      tags: [Account]
      summary: Create a new account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/delete:
    delete:
      tags: [Account]
      summary: Delete the current account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Account deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountId:
                    type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /accounts:
    get:
      tags: [Account]
      summary: Retrieve a list of accounts
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: The number of accounts to return
          required: false
          schema:
            type: integer
            format: uint64
        - name: page
          in: query
          description: The page number of accounts to retrieve
          required: false
          schema:
            type: integer
            format: uint64
      responses:
        '200':
          description: Successfully retrieved list of accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: uint64
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /privilege/{userId}:
    get:
      tags: [Account]
      summary: Get privileges by user ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved privileges for the user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortPrivilege'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/{userId}:
    delete:
      tags: [Account]
      summary: Delete account by user ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully deleted the account
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/manualdone:
    post:
      tags: [Account]
      summary: Manually mark an account as done
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: User ID to mark as done
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Account marked as done
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/leadtarget:
    post:
      tags: [Account]
      summary: Add a lead target for sending client requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - quizID
                - target
              properties:
                type:
                  type: string
                  description: Type of target (mail, telegram, whatsapp)
                  enum:
                    - mail
                    - telegram
                    - whatsapp
                quizID:
                  type: integer
                  format: int32
                  description: The associated quiz ID (0 for general rules)
                target:
                  type: string
                  description: The target address (email, channel ID, phone number)
                name:
                  type: string
                  description: Name (e.g., for Telegram channel)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lead target added successfully
        '208':
          $ref: '#/components/responses/AlreadyReportedError'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

    put:
      tags: [Account]
      summary: Update a lead target
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - target
              properties:
                id:
                  type: integer
                  format: int64
                  description: Lead target ID (primary key)
                target:
                  type: string
                  description: The target address (email, channel ID, phone number)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lead target updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/leadtarget/{id}:
    delete:
      tags: [Account]
      summary: Delete a lead target by its ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the lead target to delete
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lead target deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /account/leadtarget/{quizID}:
    get:
      tags: [Account]
      summary: Get lead target by quiz ID
      parameters:
        - name: quizID
          in: path
          required: true
          description: The quiz ID associated with the lead target
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved lead target by quiz ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadTarget'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

# TODO начиная с этого момента перепроверить чего там нагененрировал курсор
  /question/create:
    post:
      tags: [Question]
      summary: Create a new question
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionCreateRequest'
      responses:
        '200':
          description: Question created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Question'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/list:
    post:
      tags: [Question]
      summary: Get a paginated list of questions
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuestionListRequest'
      responses:
        '200':
          description: Successfully retrieved question list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuestionListResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/update:
    post:
      tags: [Question]
      summary: Update an existing question
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQuestionRequest'
      responses:
        '200':
          description: Question updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateQuestionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/copy:
    post:
      tags: [Question]
      summary: Create a copy of an existing question
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyQuestionRequest'
      responses:
        '200':
          description: Question copied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Question'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/history:
    post:
      tags: [Question]
      summary: Get question history
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuestionHistoryRequest'
      responses:
        '200':
          description: Successfully retrieved question history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuestionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/delete:
    post:
      tags: [Question]
      summary: Delete a question
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteQuestionRequest'
      responses:
        '200':
          description: Question deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteQuestionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/create:
    post:
      tags: [Quiz]
      summary: Create a new quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuizRequest'
      responses:
        '201':
          description: Quiz created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quiz'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/list:
    post:
      tags: [Quiz]
      summary: Get a paginated list of quizzes
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuizListRequest'
      responses:
        '200':
          description: Successfully retrieved quiz list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuizListResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/update:
    post:
      tags: [Quiz]
      summary: Update an existing quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQuizRequest'
      responses:
        '200':
          description: Quiz updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateQuizResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/copy:
    post:
      tags: [Quiz]
      summary: Create a copy of an existing quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyQuizRequest'
      responses:
        '200':
          description: Quiz copied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quiz'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/history:
    post:
      tags: [Quiz]
      summary: Get quiz history
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuizHistoryRequest'
      responses:
        '200':
          description: Successfully retrieved quiz history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuizHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/delete:
    post:
      tags: [Quiz]
      summary: Delete a quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteQuizRequest'
      responses:
        '200':
          description: Quiz deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteQuizResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/archive:
    post:
      tags: [Quiz]
      summary: Archive a quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveQuizRequest'
      responses:
        '200':
          description: Quiz archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveQuizResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/move:
    post:
      tags: [Quiz]
      summary: Move a quiz to another account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuizMoveRequest'
      responses:
        '200':
          description: Quiz moved successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/template/copy:
    post:
      tags: [Quiz]
      summary: Create a copy of a quiz template
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Template copied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quiz'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /results/getResults/{quizId}:
    post:
      tags: [Result]
      summary: Get results for a specific quiz
      security:
        - bearerAuth: []
      parameters:
        - name: quizId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetResultsRequest'
      responses:
        '200':
          description: Successfully retrieved quiz results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResultsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /results/{resultId}:
    delete:
      tags: [Result]
      summary: Delete a specific result
      security:
        - bearerAuth: []
      parameters:
        - name: resultId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Result deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /results/status:
    post:
      tags: [Result]
      summary: Update status of multiple results
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateResultsStatusRequest'
      responses:
        '200':
          description: Results status updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '406':
          description: Could not update some answers due to insufficient rights
        '500':
          $ref: '#/components/responses/InternalServerError'

  /results/export/{quizID}:
    post:
      tags: [Result]
      summary: Export quiz results to Excel
      security:
        - bearerAuth: []
      parameters:
        - name: quizID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetResultsRequest'
      responses:
        '200':
          description: Successfully exported results
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Payment required
        '500':
          $ref: '#/components/responses/InternalServerError'

  /results/answers/{resultID}:
    get:
      tags: [Result]
      summary: Get answers for a specific result
      security:
        - bearerAuth: []
      parameters:
        - name: resultID
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved result answers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SortedAnswer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Payment required
        '500':
          $ref: '#/components/responses/InternalServerError'

  /statistic/{quizID}/devices:
    post:
      tags: [Statistic]
      summary: Get device statistics for quiz
      security:
        - bearerAuth: []
      parameters:
        - name: quizID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceStatRequest'
      responses:
        '200':
          description: Successfully retrieved device statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceStat'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /statistic/{quizID}/general:
    post:
      tags: [Statistic]
      summary: Get general statistics for quiz
      security:
        - bearerAuth: []
      parameters:
        - name: quizID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceStatRequest'
      responses:
        '200':
          description: Successfully retrieved general statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralStatsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /statistic/{quizID}/questions:
    post:
      tags: [Statistic]
      summary: Get question statistics for quiz
      security:
        - bearerAuth: []
      parameters:
        - name: quizID
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceStatRequest'
      responses:
        '200':
          description: Successfully retrieved question statistics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QuestionStat'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /statistic:
    post:
      tags: [Statistic]
      summary: Get global service statistics
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatisticRequest'
      responses:
        '200':
          description: Successfully retrieved service statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatistics'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /statistics/{quizID}/pipelines:
    get:
      tags: [Statistic]
      summary: Get pipeline statistics for quiz
      security:
        - bearerAuth: []
      parameters:
        - name: quizID
          in: path
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: true
          schema:
            type: integer
            format: uint64
        - name: to
          in: query
          required: true
          schema:
            type: integer
            format: uint64
      responses:
        '200':
          description: Successfully retrieved pipeline statistics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PipelineStat'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /telegram/pool:
    get:
      tags: [Telegram]
      summary: Get all non-deleted Telegram accounts (active, inactive, and banned)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved Telegram accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TelegramAccount'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /telegram/create:
    post:
      tags: [Telegram]
      summary: Authorize server in Telegram account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramAuthRequest'
      responses:
        '200':
          description: Authorization started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '409':
          description: Account already exists and is active
        '500':
          $ref: '#/components/responses/InternalServerError'

  /telegram/{id}:
    delete:
      tags: [Telegram]
      summary: Soft delete Telegram account by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /telegram/setCode:
    post:
      tags: [Telegram]
      summary: Send authorization code received from Telegram
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramCodeRequest'
      responses:
        '200':
          description: Code sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          description: Authorization failed
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    UnauthorizedError:
      description: Unauthorized – authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Authentication required"
              code:
                type: integer
                example: 401

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Resource not found"
              code:
                type: integer
                example: 404

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Internal server error"
              code:
                type: integer
                example: 500

    BadRequestError:
      description: Invalid request data
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid request data"
              code:
                type: integer
                example: 400

    ConflictError:
      description: Conflict – resource already exists
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Resource already exists"
              code:
                type: integer
                example: 409

    AlreadyReportedError:
      description: Resource already used
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Resource already used"
              code:
                type: integer
                example: 208

  schemas:
    Account:
      type: object
      required:
        - id
        - user_id
        - created_at
      properties:
        id:
          type: string
          description: Unique identifier of the account
        user_id:
          type: string
          description: User identifier
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        deleted:
          type: boolean
          description: Whether the account is marked as deleted
          default: false
        privileges:
          type: object
          description: Map of privileges assigned to the account
          additionalProperties:
            $ref: '#/components/schemas/ShortPrivilege'

    ShortPrivilege:
      type: object
      required:
        - id
        - privilege_id
        - privilege_name
        - amount
        - created_at
      properties:
        id:
          type: string
          description: Unique identifier of the privilege
        privilege_id:
          type: string
          description: Privilege type identifier
        privilege_name:
          type: string
          description: Name of the privilege
        amount:
          type: integer
          format: uint64
          description: Amount or limit of the privilege
        created_at:
          type: string
          format: date-time
          description: When the privilege was granted

    LeadTarget:
      type: object
      required:
        - id
        - accountID
        - type
        - target
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the lead target
        accountID:
          type: string
          description: ID of the account that owns this target
        type:
          type: string
          description: Type of lead target
          enum: [mail, telegram, whatsapp]
        quizID:
          type: integer
          format: int32
          description: Associated quiz ID (0 for general rules)
        target:
          type: string
          description: Target address (email, channel ID, phone number)
        inviteLink:
          type: string
          description: Invite link for Telegram channel
        deleted:
          type: boolean
          description: Whether the target is marked as deleted
          default: false
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp

    CreateQuizRequest:
      type: object
      required:
        - name
      properties:
        fingerprinting:
          type: boolean
          description: Whether to store device ID
          default: false
        repeatable:
          type: boolean
          description: Whether to allow multiple quiz attempts
          default: false
        note_prevented:
          type: boolean
          description: Whether to save answers even if quiz is aborted
          default: false
        mail_notifications:
          type: boolean
          description: Whether to send email notifications for quiz completions
          default: false
        unique_answers:
          type: boolean
          description: Whether to save only the last quiz attempt
          default: false
        name:
          type: string
          description: Quiz name (max 700 characters)
          maxLength: 700
        description:
          type: string
          description: Quiz description
        config:
          type: string
          description: JSON serialized configuration for page rules
        status:
          type: string
          description: Quiz status
          enum: [draft, template, stop, start]
          default: draft
        limit:
          type: integer
          format: uint64
          description: Maximum number of quiz attempts allowed
        due_to:
          type: integer
          format: uint64
          description: Timestamp when quiz expires
        question_cnt:
          type: integer
          format: uint64
          description: Number of questions to create in one request
        time_of_passing:
          type: integer
          format: uint64
          description: Time limit for completing quiz in seconds
        pausable:
          type: boolean
          description: Whether quiz can be paused
          default: false
        super:
          type: boolean
          description: Whether this is a group quiz
          default: false
        group_id:
          type: integer
          format: uint64
          description: ID of super quiz if this is part of a group

    GetQuizListRequest:
      type: object
      properties:
        limit:
          type: integer
          format: uint64
          description: Number of items per page
          minimum: 1
          default: 10
        page:
          type: integer
          format: uint64
          description: Page number
          minimum: 1
          default: 1
        from:
          type: integer
          format: int64
          description: Start timestamp for filtering
        to:
          type: integer
          format: int64
          description: End timestamp for filtering
        search:
          type: string
          description: Search query
        status:
          type: string
          description: Filter by status
          enum: [stop, start, draft, template, timeout, offlimit]
        deleted:
          type: boolean
          description: Filter by deletion status
        archived:
          type: boolean
          description: Filter by archive status
        super:
          type: boolean
          description: Filter by group status
        group_id:
          type: integer
          format: uint64
          description: Filter by group ID

    GetQuizListResponse:
      type: object
      required:
        - count
        - items
      properties:
        count:
          type: integer
          format: uint64
          description: Total number of items
        items:
          type: array
          description: List of quizzes
          items:
            $ref: '#/components/schemas/Quiz'

    UpdateQuizRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64
        fp:
          type: boolean
        rep:
          type: boolean
        note_prevented:
          type: boolean
        mailing:
          type: boolean
        uniq:
          type: boolean
        name:
          type: string
        desc:
          type: string
        conf:
          type: string
        status:
          type: string
          enum: [draft, template, stop, start]
        limit:
          type: integer
          format: uint64
        due_to:
          type: integer
          format: uint64
        time_of_passing:
          type: integer
          format: uint64
        pausable:
          type: boolean
        question_cnt:
          type: integer
          format: uint64
        super:
          type: boolean
        group_id:
          type: integer
          format: uint64

    UpdateQuizResponse:
      type: object
      properties:
        updated:
          type: integer
          format: uint64

    CopyQuizRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64

    GetQuizHistoryRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64
        l:
          type: integer
          format: uint64
        p:
          type: integer
          format: uint64

    GetQuizHistoryResponse:
      type: object
      properties:
        count:
          type: integer
          format: uint64
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuizHistory'

    DeleteQuizRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64

    DeleteQuizResponse:
      type: object
      properties:
        deleted:
          type: integer
          format: uint64

    ArchiveQuizRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64

    ArchiveQuizResponse:
      type: object
      properties:
        archived:
          type: integer
          format: uint64

    QuizMoveRequest:
      type: object
      required:
        - qid
        - accountID
      properties:
        qid:
          type: string
        accountID:
          type: string

    QuizHistory:
      type: object
      properties:
        id:
          type: integer
          format: uint64
        quiz_id:
          type: integer
          format: uint64
        account_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
        score:
          type: number
          format: float
        time_spent:
          type: integer
          format: uint64
        answers:
          type: array
          items:
            $ref: '#/components/schemas/Answer'

    QuestionCreateRequest:
      type: object
      required:
        - quiz_id
        - title
        - type
      properties:
        quiz_id:
          type: integer
          format: uint64
          description: relation to quiz
        title:
          type: string
          description: title of question (max 512 chars)
        description:
          type: string
          description: additional content in question such as pics, html markup or plain text
        type:
          type: string
          description: type of question
          enum: [text, variant, images, select, var_images, emoji, date, number, page, rating, result, file]
        required:
          type: boolean
          description: set true if question must be answered for valid quiz passing
        page:
          type: integer
          description: set page of question
        content:
          type: string
          description: json serialized config of question

    GetQuestionListRequest:
      type: object
      properties:
        limit:
          type: integer
          format: uint64
          description: page size
        page:
          type: integer
          format: uint64
          description: page number
        from:
          type: integer
          format: int64
          description: start of time period
        to:
          type: integer
          format: int64
        quiz_id:
          type: integer
          format: uint64
          description: relation to quiz
        search:
          type: string
          description: search string to search in files
        type:
          type: string
          description: type of questions
          enum: [text, variant, images, select, var_images, emoji, date, number, page, rating, result, file]
        deleted:
          type: boolean
          description: true to get only deleted questions
        required:
          type: boolean
          description: filter by required status

    GetQuestionListResponse:
      type: object
      properties:
        count:
          type: integer
          format: uint64
        items:
          type: array
          items:
            $ref: '#/components/schemas/Question'

    UpdateQuestionRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64
        title:
          type: string
          description: title of question (max 512 chars)
        desc:
          type: string
          description: additional content in question
        type:
          type: string
          description: type of question
          enum: [text, variant, images, select, var_images, emoji, date, number, page, rating, result, file]
        required:
          type: boolean
          description: set true if question must be answered
        content:
          type: string
          description: json serialized config of question
        page:
          type: integer
          description: page number of question

    UpdateQuestionResponse:
      type: object
      properties:
        updated:
          type: integer
          format: uint64

    CopyQuestionRequest:
      type: object
      required:
        - id
        - quiz_id
      properties:
        id:
          type: integer
          format: uint64
        quiz_id:
          type: integer
          format: uint64

    GetQuestionHistoryRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64
        l:
          type: integer
          format: uint64
        p:
          type: integer
          format: uint64

    GetQuestionHistoryResponse:
      type: object
      properties:
        count:
          type: integer
          format: uint64
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuestionHistory'

    DeleteQuestionRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: uint64

    DeleteQuestionResponse:
      type: object
      properties:
        deleted:
          type: integer
          format: uint64

    QuestionHistory:
      type: object
      properties:
        id:
          type: integer
          format: uint64
        quiz_id:
          type: integer
          format: uint64
        title:
          type: string
        description:
          type: string
        type:
          type: string
        required:
          type: boolean
        page:
          type: integer
        content:
          type: string
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        parent_ids:
          type: array
          items:
            type: integer
            format: int32

    GetResultsRequest:
      type: object
      properties:
        to:
          type: string
          format: date-time
        from:
          type: string
          format: date-time
        new:
          type: boolean
        page:
          type: integer
          format: uint64
        limit:
          type: integer
          format: uint64

    GetResultsResponse:
      type: object
      properties:
        total_count:
          type: integer
          format: uint64
        results:
          type: array
          items:
            $ref: '#/components/schemas/AnswerExport'

    UpdateResultsStatusRequest:
      type: object
      required:
        - answers
      properties:
        answers:
          type: array
          items:
            type: integer
            format: int64

    SortedAnswer:
      type: object
      properties:
        id:
          type: integer
          format: uint64
        question_id:
          type: integer
          format: uint64
        title:
          type: string
        type:
          type: string
        content:
          type: string
        answer:
          type: string
        score:
          type: number
          format: float
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    DeviceStatRequest:
      type: object
      properties:
        from:
          type: integer
          format: uint64
          description: Start timestamp for statistics
        to:
          type: integer
          format: uint64
          description: End timestamp for statistics

    DeviceStat:
      type: object
      properties:
        device:
          type: string
        count:
          type: integer
          format: uint64

    GeneralStatsResponse:
      type: object
      properties:
        open:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        result:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        av_time:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        conversion:
          type: object
          additionalProperties:
            type: integer
            format: uint64

    QuestionStat:
      type: object
      properties:
        question_id:
          type: integer
          format: uint64
        title:
          type: string
        type:
          type: string
        answers:
          type: array
          items:
            $ref: '#/components/schemas/QuestionAnswerStat'

    QuestionAnswerStat:
      type: object
      properties:
        answer:
          type: string
        count:
          type: integer
          format: uint64

    StatisticRequest:
      type: object
      properties:
        from:
          type: integer
          format: uint64
          description: Start timestamp for statistics
        to:
          type: integer
          format: uint64
          description: End timestamp for statistics

    ServiceStatistics:
      type: object
      properties:
        total_quizzes:
          type: integer
          format: uint64
        total_questions:
          type: integer
          format: uint64
        total_answers:
          type: integer
          format: uint64
        total_users:
          type: integer
          format: uint64
        active_quizzes:
          type: integer
          format: uint64
        completed_quizzes:
          type: integer
          format: uint64

    PipelineStat:
      type: object
      properties:
        pipeline_id:
          type: string
        name:
          type: string
        count:
          type: integer
          format: uint64
        conversion:
          type: number
          format: float

    TelegramAccount:
      type: object
      properties:
        id:
          type: integer
          format: int64
        api_id:
          type: integer
          format: int32
        api_hash:
          type: string
        phone_number:
          type: string
        status:
          type: string
          enum: [active, inactive, banned]
        password:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    TelegramAuthRequest:
      type: object
      required:
        - api_id
        - api_hash
        - password
        - phone_number
      properties:
        api_id:
          type: integer
          format: int32
          description: Telegram API ID
        api_hash:
          type: string
          description: Telegram API Hash
        password:
          type: string
          description: Account password
        phone_number:
          type: string
          description: Phone number in international format

    TelegramCodeRequest:
      type: object
      required:
        - code
        - signature
      properties:
        code:
          type: string
          description: Authorization code received from Telegram
        signature:
          type: string
          description: Signature received from create endpoint

    Question:
      type: object
      properties:
        id:
          type: integer
          format: uint64
          description: Unique identifier of the question
        quiz_id:
          type: integer
          format: uint64
          description: ID of the quiz this question belongs to
        title:
          type: string
          description: Title of the question
        description:
          type: string
          description: Additional description or content of the question
        type:
          type: string
          description: Type of the question
          enum: [text, variant, images, select, var_images, emoji, date, number, page, rating, result, file]
        required:
          type: boolean
          description: Whether the question must be answered
        deleted:
          type: boolean
          description: Whether the question is marked as deleted
        page:
          type: integer
          description: Page number where the question appears
        content:
          type: string
          description: JSON serialized configuration of the question
        version:
          type: integer
          description: Version number of the question
        parent_ids:
          type: array
          items:
            type: integer
            format: int32
          description: IDs of parent questions if this is a child question
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp

    Quiz:
      type: object
      properties:
        id:
          type: integer
          format: uint64
          description: Unique identifier of the quiz
        qid:
          type: string
          description: Quiz identifier string
        accountid:
          type: string
          description: ID of the account that owns the quiz
        deleted:
          type: boolean
          description: Whether the quiz is marked as deleted
        archived:
          type: boolean
          description: Whether the quiz is archived
        fingerprinting:
          type: boolean
          description: Whether device fingerprinting is enabled
        repeatable:
          type: boolean
          description: Whether the quiz can be taken multiple times
        note_prevented:
          type: boolean
          description: Whether answers are saved even if quiz is aborted
        mail_notifications:
          type: boolean
          description: Whether email notifications are enabled for quiz completions
        unique_answers:
          type: boolean
          description: Whether only the last quiz attempt is saved
        name:
          type: string
          description: Name of the quiz
        description:
          type: string
          description: Description of the quiz
        config:
          type: string
          description: JSON serialized configuration for page rules
        status:
          type: string
          description: Current status of the quiz
          enum: [draft, template, stop, start]
        limit:
          type: integer
          format: uint64
          description: Maximum number of quiz attempts allowed
        due_to:
          type: integer
          format: uint64
          description: Timestamp when the quiz expires
        time_of_passing:
          type: integer
          format: uint64
          description: Time limit for completing the quiz in seconds
        pausable:
          type: boolean
          description: Whether the quiz can be paused
        version:
          type: integer
          description: Version number of the quiz
        version_comment:
          type: string
          description: Comment for the current version
        parent_ids:
          type: array
          items:
            type: integer
            format: int32
          description: IDs of parent quizzes if this is a child quiz
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        questions_count:
          type: integer
          format: uint64
          description: Number of questions in the quiz
        session_count:
          type: integer
          format: uint64
          description: Number of quiz sessions started
        passed_count:
          type: integer
          format: uint64
          description: Number of completed quiz attempts
        average_time:
          type: integer
          format: uint64
          description: Average time taken to complete the quiz in seconds
        super:
          type: boolean
          description: Whether this is a super quiz (group)
        group_id:
          type: integer
          format: uint64
          description: ID of the super quiz if this quiz belongs to a group

    UTMSavingMap:
      type: object
      additionalProperties:
        type: string
      description: Map of UTM parameters and their values

    Answer:
      type: object
      properties:
        id:
          type: integer
          format: uint64
          description: Unique identifier of the answer
        content:
          type: string
          description: Serialized JSON content of the answer (empty for buttons)
        question_id:
          type: integer
          format: uint64
          description: ID of the question this answer belongs to
        quiz_id:
          type: integer
          format: uint64
          description: ID of the quiz this answer belongs to
        fingerprint:
          type: string
          description: Device identifier
        session:
          type: string
          description: Session identifier (xid)
        result:
          type: boolean
          description: Whether this is a result answer
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        new:
          type: boolean
          description: Whether this is a new answer
        deleted:
          type: boolean
          description: Whether the answer is marked as deleted
        email:
          type: string
          description: Email address associated with the answer
        device_type:
          type: string
          description: Type of device used
        device:
          type: string
          description: Device information
        browser:
          type: string
          description: Browser information
        ip:
          type: string
          description: IP address
        os:
          type: string
          description: Operating system information
        start:
          type: boolean
          description: Whether this is a start answer
        utm:
          $ref: '#/components/schemas/UTMSavingMap'
          description: UTM parameters
        version:
          type: integer
          format: int32
          description: Version number

    AnswerExport:
      type: object
      properties:
        content:
          type: string
          description: Serialized JSON content of the answer
        id:
          type: integer
          format: uint64
          description: Unique identifier of the answer
        new:
          type: boolean
          description: Whether this is a new answer
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        version:
          type: integer
          format: int32
          description: Version number