core/api/openapi2.yaml

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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  format: uint64
                page:
                  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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  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'

  /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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/getList:
    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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/edit:
    patch:
      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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/Question'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /question/delete:
    delete:
      tags: [Question]
      summary: Delete a question
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeactivateQuestionRequest'
      responses:
        '200':
          description: Question deleted successfully    
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeactivateQuestionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '409':
          $ref: '#/components/responses/StatusConflictError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/getList:
    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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/edit:
    patch:
      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'
        '406':
          $ref: '#/components/responses/StatusNotAcceptableError'
        '409':
          $ref: '#/components/responses/StatusConflictError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/Quiz'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/delete:
    delete:
      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'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /quiz/archive:
    patch:
      tags: [Quiz]
      summary: Archive a quiz
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteQuizRequest'
      responses:
        '200':
          description: Quiz archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteQuizResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '424':
          $ref: '#/components/responses/StatusFailedDependencyError'
        '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:
    post:
      tags: [Quiz]
      summary: Create a copy of a quiz template
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Template copied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
        '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'

  /result/seen:
    patch:
      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/{quizID}/export:
    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'

  /result/{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/Answer'
        '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/DeviceStatRequest'
      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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceStatRequest'
      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
    StatusNotAcceptableError:
      description: Status not acceptable – requested format not supported
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Requested format not acceptable"
              code:
                type: integer
                example: 406

    StatusFailedDependencyError:
      description: Failed dependency – a prerequisite condition failed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "A prerequisite condition failed"
              code:
                type: integer
                example: 424

    StatusConflictError:
      description: Conflict – request could not be completed due to conflict with current state
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Conflict with current state"
              code:
                type: integer
                example: 409



  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

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

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

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

    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, varimg, 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

    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, varimg, 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, varimg, 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
        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

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

    DeactivateQuestionResponse:
      type: object
      properties:
        deactivated:
          type: integer
          format: uint64

    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

    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: object
          additionalProperties:
            type: number
            format: float
          description: Percentage distribution of device types across all answers with res=true
        OS:
          type: object
          additionalProperties:
            type: number
            format: float
          description: Percentage distribution of operating systems across all answers with res=true
        Browser:
          type: object
          additionalProperties:
            type: number
            format: float
          description: Percentage distribution of browsers across all answers with res=true

    GeneralStatsResponse:
      type: object
      properties:
        Open:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        Result:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        AvTime:
          type: object
          additionalProperties:
            type: integer
            format: uint64
        Conversion:
          type: object
          additionalProperties:
            type: integer
            format: uint64

    QuestionStat:
      type: object
      properties:
        Funnel:
          type: array
          items:
            type: number
            format: float
          maxItems: 3
          description: Three separate funnel metrics
        FunnelData:
          type: array
          items:
            type: number
            format: float
          maxItems: 4
          description: Funnel data metrics
        Results:
          type: object
          additionalProperties:
            type: number
            format: float
          description: Map of question titles to percentage of answers with result=true
        Questions:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
              format: float
          description: Map of question titles to their answer distributions

    ServiceStatistics:
      type: object
      properties:
        Registrations:
          type: integer
          format: int64
          description: Number of registered accounts from from to to
        Quizes:
          type: integer
          format: int64
          description: Number of created non-deleted quizzes
        Results:
          type: integer
          format: int64
          description: Number of answers with result=true

    PipelineStat:
      type: object
      additionalProperties:
        type: array
        items:
          type: object
          properties:
            count:
              type: integer
              format: int64
            questionID:
              type: integer
              format: int64

    TelegramAccount:
      type: object
      properties:
        ID:
          type: integer
          format: int64
          description: Unique identifier of the Telegram account
        ApiID:
          type: integer
          format: int32
          description: Telegram API ID
        ApiHash:
          type: string
          description: Telegram API Hash
        PhoneNumber:
          type: string
          description: Phone number in international format
        Password:
          type: string
          description: Account password
        Status:
          type: string
          enum: [active, inactive, ban]
          description: Current status of the Telegram account
        Deleted:
          type: boolean
          description: Whether the account is marked as deleted
        CreatedAt:
          type: string
          format: date-time
          description: Creation timestamp

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

    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: Relation to quiz table
        title:
          type: string
          description: Title of question
        description:
          type: string
          description: HTML/text representation of question and question description for answerer
        type:
          type: string
          description: Type field
          enum: [variant, images, varimg, file, text, emoji, select, date, number, page, rating, result]
        required:
          type: boolean
          description: Answerer must answer this question
        deleted:
          type: boolean
          description: Fake deleting field
        page:
          type: integer
          description: Set page number for question
        content:
          type: string
          description: Serialized JSON content
        version:
          type: integer
          description: Version number
        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: UUID for secure data get and post
        accountid:
          type: string
          description: Account that created the quiz
        deleted:
          type: boolean
          description: Fake delete field
        archived:
          type: boolean
          description: Field for archiving quiz
        fingerprinting:
          type: boolean
          description: Field that need for storing device id
        repeatable:
          type: boolean
          description: Make it true for allow more than one quiz checkouting
        note_prevented:
          type: boolean
          description: Note answers even if the quiz was aborted
        mail_notifications:
          type: boolean
          description: Set true if you want get an email with every quiz passing
        unique_answers:
          type: boolean
          description: Set true if we you mention only last quiz passing
        name:
          type: string
          description: Quiz name
        description:
          type: string
          description: Quiz description
        config:
          type: string
          description: Serialize json with config for page rules
        status:
          type: string
          description: Status of quiz as enum
          enum: [draft, template, stop, start, timeout, offlimit]
        limit:
          type: integer
          format: uint64
          description: Max count of quiz passing
        due_to:
          type: integer
          format: uint64
          description: Time when quiz is end
        time_of_passing:
          type: integer
          format: uint64
          description: Amount of seconds for give all appropriate answers for quiz
        pausable:
          type: boolean
          description: True allows to pause the quiz taking
        version:
          type: integer
          description: Version number
        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
        QuizId:
          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
        CreatedAt:
          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
        DeviceType:
          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