openapi: 3.0.1
info:
  title: ' Taskbase Public API'
  version: 0.9.0
servers:
  - url: /
security:
  - bearerAuth: []
paths:
  /feedback/compute:
    post:
      tags:
        - Feedback
      summary: Computes feedback for the provided task and answer
      operationId: computeFeedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feedback'
        '400':
          description: |2-

                                The request is malformed, possibly due to an invalid or missing authorization field
                                or an incorrect schema in the request body.
                            
        '403':
          description: Forbidden - API user does not have access to this tenant
        '500':
          description: |2-

                                An internal server error occurred. While this error is unlikely, the message will include
                                an identifier to help with quick troubleshooting.
                            
      security:
        - bearerAuth: []
  /interactions/{interactionId}/end-user-rating:
    put:
      tags:
        - Interactions
      summary: Creates or updates an end-user feedback rating.
      description: |2-

                    There can be only one rating per interaction, therefore this operation does an update when called more than
                    once with the same data. The api user acts on behalf of the end-user who is supposed to be the creator of the interaction.
                
      operationId: putEndUserFeedbackRating
      parameters:
        - name: interactionId
          in: path
          description: The interaction identifier
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserFeedbackRating'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUserFeedbackRating'
        '400':
          description: Invalid request - malformed interaction ID or rating data
        '403':
          description: Forbidden - API user does not have access to this tenant
        '404':
          description: Interaction not found or task does not exist
      security:
        - bearerAuth: []
  /simulation/start:
    post:
      tags:
        - Simulation
      summary: Starts a new simulation session.
      description: |2-

                    Creates a new simulation session for the specified task. This includes:
                    - Ensuring the AI tutor configuration exists
                    - Initializing the conversation context with system prompts
                    - Creating a unique conversation ID for the session

                    The API user acts on behalf of the end-user and must have appropriate access to the task.
                
      operationId: startSimulationSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSimulationSessionRequest'
        required: true
      responses:
        '200':
          description: Simulation session response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationSession'
      security:
        - bearerAuth: []
  /tasks/{taskId}/feedback/compute:
    post:
      tags:
        - Tasks
      summary: Computes feedback for an existing task.
      operationId: computeFeedbackByTaskId
      parameters:
        - name: taskId
          in: path
          description: The ID of the task.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequestByTaskId'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feedback'
        '400':
          description: Invalid request - malformed answer data or task type mismatch
        '403':
          description: Forbidden - API user does not have access to this tenant
        '404':
          description: Task not found
      security:
        - bearerAuth: []
  /tasks/aspects/compute:
    post:
      tags:
        - Tasks
      summary: Returns all relevant Aspects for a given task.
      operationId: computeTaskAspects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskAspectsRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Aspect'
        '400':
          description: Invalid request - malformed task data or missing required fields
        '403':
          description: Forbidden - API user does not have access to this tenant
      security:
        - bearerAuth: []
components:
  schemas:
    Answer:
      type: object
      description: Base class for task answers. The concrete type depends on the task type.
      oneOf:
        - $ref: '#/components/schemas/FreeformTextAnswer'
        - $ref: '#/components/schemas/InTextFillInBlanksAnswer'
        - $ref: '#/components/schemas/InTextChoicesAnswer'
        - $ref: '#/components/schemas/MultipleChoiceAnswer'
        - $ref: '#/components/schemas/MultipleResponsesAnswer'
        - $ref: '#/components/schemas/SimulationAnswer'
    Aspect:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          description: >-
            Indicates whether an Aspect represents a misconception (wrong
            aspect) or a concept (correct aspect).
          enum:
            - CONCEPT
            - MISCONCEPTION
        aspectGroup:
          $ref: '#/components/schemas/AspectGroup'
      description: Aspect information.
    AspectGroup:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
      description: The group to which the Aspect belongs.
    DetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
    Feedback:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/FeedbackResult'
        metaData:
          $ref: '#/components/schemas/FeedbackMetaData'
        taskType:
          type: string
          description: >-
            Defines the type of the task. Can be used by deserialization tools
            to instantiate the correct sub-type.
          enum:
            - FREEFORM_TEXT
            - IN_TEXT_FILL_IN_BLANKS
            - IN_TEXT_CHOICES
            - MULTIPLE_CHOICE
            - MULTIPLE_RESPONSES
            - SIMULATION
        taskId:
          type: string
        userId:
          type: string
      discriminator:
        propertyName: taskType
    FeedbackItem:
      type: object
      properties:
        message:
          type: string
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
    FeedbackMetaData:
      type: object
      properties:
        taskAction:
          type: string
          description: The action that was performed on the task.
          enum:
            - CREATED
            - UPDATED
            - UNCHANGED
        tenantId:
          type: string
        taskLink:
          type: string
      description: |2-

                The object containing metadata about the performed operation, along with helpful debugging information.
                Designed to simplify the integration process and does not include any production-related details that should be visible to the end user.
            
    FeedbackResult:
      type: object
      properties:
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/DetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/FeedbackItem'
        points:
          $ref: '#/components/schemas/Points'
        answer:
          $ref: '#/components/schemas/Answer'
    FreeformTextAnswer:
      type: object
      properties:
        content:
          type: string
      description: Answer for freeform text tasks.
    FreeformTextContext:
      type: object
      properties:
        content:
          type: string
        offset:
          type: integer
          format: int32
        length:
          type: integer
          format: int32
    FreeformTextDetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          type: array
          items:
            $ref: '#/components/schemas/FreeformTextContext'
    FreeformTextFeedback:
      type: object
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/FreeformTextFeedbackResult'
    FreeformTextFeedbackItem:
      type: object
      properties:
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
        message:
          type: string
        context:
          type: array
          items:
            $ref: '#/components/schemas/FreeformTextContext'
    FreeformTextFeedbackResult:
      type: object
      properties:
        sampleSolutions:
          type: array
          items:
            $ref: '#/components/schemas/FreeformTextSampleSolution'
        sampleSolution:
          $ref: '#/components/schemas/FreeformTextSampleSolution'
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/FreeformTextDetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/FreeformTextFeedbackItem'
        answer:
          $ref: '#/components/schemas/FreeformTextAnswer'
        points:
          $ref: '#/components/schemas/Points'
    FreeformTextSampleSolution:
      type: object
      properties:
        content:
          type: string
      description: Sample solution for freeform text tasks.
    InTextChoicesAnswer:
      type: object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesAnswerOption'
      description: Answer for in-text choices tasks.
    InTextChoicesAnswerOption:
      type: object
      properties:
        content:
          type: string
      description: Answer option for in-text choices tasks.
    InTextChoicesContext:
      type: object
      properties:
        content:
          type: string
        index:
          type: integer
          format: int32
    InTextChoicesDetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/InTextChoicesContext'
    InTextChoicesFeedback:
      type: object
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/InTextChoicesFeedbackResult'
    InTextChoicesFeedbackItem:
      type: object
      properties:
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
        message:
          type: string
        context:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesContext'
    InTextChoicesFeedbackResult:
      type: object
      properties:
        sampleSolution:
          $ref: '#/components/schemas/InTextChoicesSampleSolution'
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesDetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesFeedbackItem'
        answer:
          $ref: '#/components/schemas/InTextChoicesAnswer'
        points:
          $ref: '#/components/schemas/Points'
    InTextChoicesSampleSolution:
      type: object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesSampleSolutionChoice'
      description: Sample solution for in-text choices tasks.
    InTextChoicesSampleSolutionChoice:
      type: object
      properties:
        content:
          type: string
      description: Sample solution choice for in-text choices tasks.
    InTextFillInBlanksAnswer:
      type: object
      properties:
        blanks:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksAnswerBlank'
      description: Answer for in-text fill-in-blanks tasks.
    InTextFillInBlanksAnswerBlank:
      type: object
      properties:
        content:
          type: string
      description: Answer blank for in-text fill-in-blanks tasks.
    InTextFillInBlanksContext:
      type: object
      properties:
        content:
          type: string
        index:
          type: integer
          format: int32
    InTextFillInBlanksDetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/InTextFillInBlanksContext'
    InTextFillInBlanksFeedback:
      type: object
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/InTextFillInBlanksFeedbackResult'
    InTextFillInBlanksFeedbackItem:
      type: object
      properties:
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
        message:
          type: string
        context:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksContext'
    InTextFillInBlanksFeedbackResult:
      type: object
      properties:
        sampleSolution:
          $ref: '#/components/schemas/InTextFillInBlanksSampleSolution'
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksDetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksFeedbackItem'
        answer:
          $ref: '#/components/schemas/InTextFillInBlanksAnswer'
        points:
          $ref: '#/components/schemas/Points'
    InTextFillInBlanksSampleSolution:
      type: object
      properties:
        blanks:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksSampleSolutionBlank'
      description: Sample solution for in-text fill-in-blanks tasks.
    InTextFillInBlanksSampleSolutionBlank:
      type: object
      properties:
        content:
          type: string
      description: Sample solution blank for in-text fill-in-blanks tasks.
    MultipleChoiceAnswer:
      type: object
      properties:
        selectedIndex:
          type: integer
          format: int32
      description: Answer for multiple choice tasks.
    MultipleChoiceContext:
      type: object
      properties:
        index:
          type: integer
          format: int32
        selected:
          type: boolean
    MultipleChoiceDetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/MultipleChoiceContext'
    MultipleChoiceFeedback:
      type: object
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/MultipleChoiceFeedbackResult'
    MultipleChoiceFeedbackItem:
      type: object
      properties:
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
        message:
          type: string
        context:
          type: array
          items:
            $ref: '#/components/schemas/MultipleChoiceContext'
    MultipleChoiceFeedbackResult:
      type: object
      properties:
        sampleSolution:
          $ref: '#/components/schemas/MultipleChoiceSampleSolution'
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/MultipleChoiceDetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/MultipleChoiceFeedbackItem'
        answer:
          $ref: '#/components/schemas/MultipleChoiceAnswer'
        points:
          $ref: '#/components/schemas/Points'
    MultipleChoiceSampleSolution:
      type: object
      properties:
        selectedIndex:
          type: integer
          format: int32
      description: Sample solution for multiple choice tasks.
    MultipleResponsesAnswer:
      type: object
      properties:
        selected:
          type: array
          items:
            type: boolean
      description: Answer for multiple responses tasks.
    MultipleResponsesContext:
      type: object
      properties:
        index:
          type: integer
          format: int32
        selected:
          type: boolean
    MultipleResponsesDetectedAspect:
      type: object
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/MultipleResponsesContext'
    MultipleResponsesFeedback:
      type: object
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          properties:
            result:
              $ref: '#/components/schemas/MultipleResponsesFeedbackResult'
    MultipleResponsesFeedbackItem:
      type: object
      properties:
        correctness:
          type: string
          description: The correctness of the learner's answer.
          enum:
            - CORRECT
            - PARTIAL
            - WRONG
            - UNKNOWN
        topic:
          $ref: '#/components/schemas/Topic'
        aspects:
          type: array
          items:
            $ref: '#/components/schemas/Aspect'
        message:
          type: string
        context:
          type: array
          items:
            $ref: '#/components/schemas/MultipleResponsesContext'
    MultipleResponsesFeedbackResult:
      type: object
      properties:
        sampleSolution:
          $ref: '#/components/schemas/MultipleResponsesSampleSolution'
        allAspects:
          type: array
          items:
            $ref: '#/components/schemas/MultipleResponsesDetectedAspect'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/MultipleResponsesFeedbackItem'
        answer:
          $ref: '#/components/schemas/MultipleResponsesAnswer'
        points:
          $ref: '#/components/schemas/Points'
    MultipleResponsesSampleSolution:
      type: object
      properties:
        selected:
          type: array
          items:
            type: boolean
      description: Sample solution for multiple responses tasks.
    Points:
      type: object
      properties:
        achievedPoints:
          type: number
          format: double
        achievablePoints:
          type: number
          format: double
      description: >-
        The object containing information on how many points the student
        achieved.
    SimulationAnswer:
      type: object
      properties:
        simulationSessionId:
          type: string
        conversation:
          $ref: '#/components/schemas/SimulationConversation'
      description: Answer for simulation tasks.
    SimulationConversation:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/SimulationMessage'
      description: Conversation data for simulation tasks.
    SimulationMessage:
      type: object
      properties:
        content:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
            - system
      description: Individual message in a simulation conversation.
    Topic:
      type: object
      properties:
        name:
          type: string
      description: Topic information.
    FeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      properties:
        metaData:
          $ref: '#/components/schemas/FeedbackRequestMetaData'
        taskType:
          type: string
          description: >-
            Defines the type of the task. Can be used by deserialization tools
            to instantiate the correct sub-type.
          enum:
            - FREEFORM_TEXT
            - IN_TEXT_FILL_IN_BLANKS
            - IN_TEXT_CHOICES
            - MULTIPLE_CHOICE
            - MULTIPLE_RESPONSES
            - SIMULATION
        tenantId:
          type: string
          description: Tenant identifier.
        answer:
          $ref: '#/components/schemas/Answer'
        userId:
          type: string
          description: User identifier.
        taskDefinition:
          $ref: '#/components/schemas/Task'
      description: >-
        Base class for feedback requests. The actual type is determined by the
        taskType field.
      discriminator:
        propertyName: taskType
        mapping:
          FREEFORM_TEXT: '#/components/schemas/FreeformTextFeedbackRequest'
          IN_TEXT_FILL_IN_BLANKS: '#/components/schemas/InTextFillInBlanksFeedbackRequest'
          IN_TEXT_CHOICES: '#/components/schemas/InTextChoicesFeedbackRequest'
          MULTIPLE_CHOICE: '#/components/schemas/MultipleChoiceFeedbackRequest'
          MULTIPLE_RESPONSES: '#/components/schemas/MultipleResponsesFeedbackRequest'
      oneOf:
        - $ref: '#/components/schemas/FreeformTextFeedbackRequest'
        - $ref: '#/components/schemas/InTextFillInBlanksFeedbackRequest'
        - $ref: '#/components/schemas/InTextChoicesFeedbackRequest'
        - $ref: '#/components/schemas/MultipleChoiceFeedbackRequest'
        - $ref: '#/components/schemas/MultipleResponsesFeedbackRequest'
    FeedbackRequestMetaData:
      type: object
      properties:
        timeOnTask:
          type: integer
          format: int32
        tryCount:
          type: integer
          format: int32
        sessionId:
          type: string
      description: The object containing metadata related to the learner interaction.
    FreeformTextFeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      description: Feedback request for freeform text tasks.
      example:
        userId: student123
        taskType: FREEFORM_TEXT
        taskDefinition:
          id: task_waterloo
          problemStatement: When was the Battle of Waterloo?
          type: FREEFORM_TEXT
          sampleSolutions:
            - content: The Battle of Waterloo was in 1815.
        answer:
          content: The Battle of Waterloo was in 1815.
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - type: object
          properties:
            taskDefinition:
              $ref: '#/components/schemas/FreeformTextTask'
            answer:
              $ref: '#/components/schemas/FreeformTextAnswer'
    FreeformTextResource:
      type: object
      properties:
        type:
          type: string
          description: The supported media file type.
          enum:
            - AUDIO
        format:
          type: string
          description: The audio file format.
          enum:
            - MP3
        src:
          type: string
      description: The object containing information about the media file.
    FreeformTextTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: Freeform text task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            sampleSolution:
              type: string
            sampleSolutions:
              type: array
              items:
                $ref: '#/components/schemas/FreeformTextSampleSolution'
            context:
              type: string
            resource:
              $ref: '#/components/schemas/FreeformTextResource'
    InTextChoiceOption:
      type: object
      properties:
        option:
          type: string
        correct:
          type: boolean
      description: Option for in-text choices.
    InTextChoicesChoice:
      type: object
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoiceOption'
      description: Choice definition for in-text choices tasks.
    InTextChoicesFeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      description: Feedback request for in-text choices tasks.
      example:
        userId: student123
        taskType: IN_TEXT_CHOICES
        taskDefinition:
          id: task_choices
          problemStatement: Select the correct options
          type: IN_TEXT_CHOICES
          textWithChoices: The capital of France is {--}.
          choices:
            - options:
                - option: Berlin
                  isCorrect: false
                - option: Paris
                  isCorrect: true
        answer:
          choices:
            - content: Paris
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - type: object
          properties:
            taskDefinition:
              $ref: '#/components/schemas/InTextChoicesTask'
            answer:
              $ref: '#/components/schemas/InTextChoicesAnswer'
    InTextChoicesTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: In-text choices task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            textWithChoices:
              type: string
            choices:
              type: array
              items:
                $ref: '#/components/schemas/InTextChoicesChoice'
    InTextFillInBlanksBlank:
      type: object
      properties:
        solutions:
          type: array
          items:
            $ref: '#/components/schemas/InTextFillInBlanksSolution'
      description: Blank definition for in-text fill-in-blanks tasks.
    InTextFillInBlanksFeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      description: Feedback request for in-text fill-in-blanks tasks.
      example:
        userId: student123
        taskType: IN_TEXT_FILL_IN_BLANKS
        taskDefinition:
          id: task_blanks
          problemStatement: Fill in the blanks
          type: IN_TEXT_FILL_IN_BLANKS
          textWithBlanks: The battle of Waterloo was in {--}. It was the last battle of {--}.
          blanks:
            - solutions:
                - content: '1815'
            - solutions:
                - content: Napoleon
        answer:
          blanks:
            - content: '1815'
            - content: Napoleon
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - type: object
          properties:
            taskDefinition:
              $ref: '#/components/schemas/InTextFillInBlanksTask'
            answer:
              $ref: '#/components/schemas/InTextFillInBlanksAnswer'
    InTextFillInBlanksSolution:
      type: object
      properties:
        content:
          type: string
      description: Solution for a blank in in-text fill-in-blanks tasks.
    InTextFillInBlanksTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: In-text fill-in-blanks task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            blanks:
              type: array
              items:
                $ref: '#/components/schemas/InTextFillInBlanksBlank'
            textWithBlanks:
              type: string
    MultipleChoiceFeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      description: Feedback request for multiple choice tasks.
      example:
        userId: student123
        taskType: MULTIPLE_CHOICE
        taskDefinition:
          id: task_capitals
          problemStatement: What is the capital of France?
          type: MULTIPLE_CHOICE
          indexOfSolution: 1
          choices:
            - option:
                text: Berlin
            - option:
                text: Paris
            - option:
                text: Madrid
        answer:
          selectedIndex: 1
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - type: object
          properties:
            taskDefinition:
              $ref: '#/components/schemas/MultipleChoiceTask'
            answer:
              $ref: '#/components/schemas/MultipleChoiceAnswer'
    MultipleChoiceOption:
      type: object
      properties:
        option:
          $ref: '#/components/schemas/MultipleChoiceOptionContent'
      description: Option for multiple choice tasks.
    MultipleChoiceOptionContent:
      type: object
      properties:
        text:
          type: string
      description: Content for multiple choice option.
    MultipleChoiceTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: Multiple choice task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            indexOfSolution:
              type: integer
              format: int32
            choices:
              type: array
              items:
                $ref: '#/components/schemas/MultipleChoiceOption'
    MultipleResponsesFeedbackRequest:
      required:
        - answer
        - taskDefinition
        - taskType
        - userId
      type: object
      description: Feedback request for multiple responses tasks.
      example:
        userId: student123
        taskType: MULTIPLE_RESPONSES
        taskDefinition:
          id: task_multiresponse
          problemStatement: Which of these are European capitals?
          type: MULTIPLE_RESPONSES
          indicesOfSolutions:
            - 0
            - 2
          choices:
            - option:
                text: Paris
            - option:
                text: Tokyo
            - option:
                text: Berlin
        answer:
          selected:
            - true
            - false
            - true
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - type: object
          properties:
            taskDefinition:
              $ref: '#/components/schemas/MultipleResponsesTask'
            answer:
              $ref: '#/components/schemas/MultipleResponsesAnswer'
    MultipleResponsesOption:
      type: object
      properties:
        option:
          $ref: '#/components/schemas/MultipleResponsesOptionContent'
      description: Option for multiple responses tasks.
    MultipleResponsesOptionContent:
      type: object
      properties:
        text:
          type: string
      description: Content for multiple responses option.
    MultipleResponsesTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: Multiple responses task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            indicesOfSolutions:
              type: array
              items:
                type: integer
                format: int32
            choices:
              type: array
              items:
                $ref: '#/components/schemas/MultipleResponsesOption'
    SimulationTask:
      required:
        - id
        - problemStatement
        - type
      type: object
      description: Simulation task.
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            sampleSolution:
              type: string
            scenarioDescription:
              type: string
            initialMessage:
              type: string
            timeLimitInMinutes:
              type: integer
              format: int32
    Task:
      required:
        - id
        - problemStatement
        - type
      type: object
      properties:
        id:
          type: string
          description: >-
            The task ID. This field should contain the task identifier used in
            the client's system.
        type:
          type: string
          description: >-
            Defines the type of the task. Can be used by deserialization tools
            to instantiate the correct sub-type.
          enum:
            - FREEFORM_TEXT
            - IN_TEXT_FILL_IN_BLANKS
            - IN_TEXT_CHOICES
            - MULTIPLE_CHOICE
            - MULTIPLE_RESPONSES
            - SIMULATION
        language:
          type: string
          description: The task language.
          enum:
            - DE_CH
            - DE_DE
            - EN_US
            - EN_UK
            - FR_FR
            - IT_IT
            - ES_ES
          default: EN_US
        title:
          type: string
          description: |2-

                        The task title. If left blank, the `taskDefinition.id` will be used as the title
                        during implicit task creation or update.
                    
          example: my_task_title
        problemStatement:
          type: string
          description: The problem statement of the task.
          example: When was the Battle of Waterloo?
      discriminator:
        propertyName: type
    EndUserFeedbackRating:
      type: object
      properties:
        type:
          type: string
          enum:
            - GOOD
            - BAD
        subtype:
          type: string
          enum:
            - UNCLEAR_EXPLANATION
            - UNHELPFUL
            - TOO_STRICT
            - INCORRECT_FEEDBACK
            - TOO_GENERIC
            - NOT_RELEVANT
            - CLEAR_EXPLANATION
            - HELPFUL_HINT
            - MOTIVATION_BOOST
            - CORRECT_ANSWER
            - LEARNED_SOMETHING_NEW
            - LIKED_FORMAT
        message:
          type: string
      description: End user feedback rating.
      example:
        type: GOOD
        subtype: HELPFUL_HINT
        message: This feedback was very helpful!
    SimulationSession:
      required:
        - id
        - initialMessages
        - taskId
        - tutorId
        - userId
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the simulation session.
        taskId:
          type: string
          description: The task ID associated with this simulation session.
        userId:
          type: integer
          description: The user ID who started the simulation session.
          format: int64
        transactionId:
          type: integer
          description: >-
            The transaction ID associated with this simulation session, if
            available.
          format: int64
        tutorId:
          type: string
          description: The ID of the tutor that provides the tutor interactions.
        initialMessages:
          $ref: '#/components/schemas/SimulationConversation'
      description: A simulation session.
    StartSimulationSessionRequest:
      required:
        - simulationTask
        - tenantId
      type: object
      properties:
        simulationTask:
          $ref: '#/components/schemas/SimulationTask'
        tenantId:
          type: string
          description: The ID of the tenant the simulation is associated with.
      description: Request to start a simulation session.
      example:
        simulationTask:
          id: sim_task_123
          type: SIMULATION
          language: EN_US
          title: Customer Service Roleplay
          problemStatement: Practice handling a customer complaint
          scenarioDescription: >-
            You are a customer service representative. A customer is upset about
            a delayed order.
          initialMessage: Hello, I need to speak with someone about my order!
          timeLimitInMinutes: 15
        tenantId: tenant_123
    FeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      properties:
        metaData:
          $ref: '#/components/schemas/FeedbackRequestMetaData'
        taskType:
          type: string
          description: >-
            Defines the type of the task. Can be used by deserialization tools
            to instantiate the correct sub-type.
          enum:
            - FREEFORM_TEXT
            - IN_TEXT_FILL_IN_BLANKS
            - IN_TEXT_CHOICES
            - MULTIPLE_CHOICE
            - MULTIPLE_RESPONSES
            - SIMULATION
        tenantId:
          type: string
          description: Tenant identifier.
        answer:
          $ref: '#/components/schemas/Answer'
        userId:
          type: string
          description: User identifier.
      description: >-
        Base class for feedback requests by task ID. The actual type is
        determined by the taskType field.
      discriminator:
        propertyName: taskType
        mapping:
          FREEFORM_TEXT: '#/components/schemas/FreeformTextFeedbackRequestByTaskId'
          IN_TEXT_FILL_IN_BLANKS: '#/components/schemas/InTextFillInBlanksFeedbackRequestByTaskId'
          IN_TEXT_CHOICES: '#/components/schemas/InTextChoicesFeedbackRequestByTaskId'
          MULTIPLE_CHOICE: '#/components/schemas/MultipleChoiceFeedbackRequestByTaskId'
          MULTIPLE_RESPONSES: '#/components/schemas/MultipleResponsesFeedbackRequestByTaskId'
      oneOf:
        - $ref: '#/components/schemas/FreeformTextFeedbackRequestByTaskId'
        - $ref: '#/components/schemas/InTextFillInBlanksFeedbackRequestByTaskId'
        - $ref: '#/components/schemas/InTextChoicesFeedbackRequestByTaskId'
        - $ref: '#/components/schemas/MultipleChoiceFeedbackRequestByTaskId'
        - $ref: '#/components/schemas/MultipleResponsesFeedbackRequestByTaskId'
    FreeformTextFeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      description: Feedback request by task ID for freeform text tasks.
      example:
        userId: student123
        taskType: FREEFORM_TEXT
        answer:
          content: The Battle of Waterloo was in 1815.
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          properties:
            answer:
              $ref: '#/components/schemas/FreeformTextAnswer'
    InTextChoicesFeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      description: Feedback request by task ID for in-text choices tasks.
      example:
        userId: student123
        taskType: IN_TEXT_CHOICES
        answer:
          choices:
            - content: Paris
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          properties:
            answer:
              $ref: '#/components/schemas/InTextChoicesAnswer'
    InTextFillInBlanksFeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      description: Feedback request by task ID for in-text fill-in-blanks tasks.
      example:
        userId: student123
        taskType: IN_TEXT_FILL_IN_BLANKS
        answer:
          blanks:
            - content: '1815'
            - content: Napoleon
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          properties:
            answer:
              $ref: '#/components/schemas/InTextFillInBlanksAnswer'
    MultipleChoiceFeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      description: Feedback request by task ID for multiple choice tasks.
      example:
        userId: student123
        taskType: MULTIPLE_CHOICE
        answer:
          selectedIndex: 1
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          properties:
            answer:
              $ref: '#/components/schemas/MultipleChoiceAnswer'
    MultipleResponsesFeedbackRequestByTaskId:
      required:
        - answer
        - taskType
        - userId
      type: object
      description: Feedback request by task ID for multiple responses tasks.
      example:
        userId: student123
        taskType: MULTIPLE_RESPONSES
        answer:
          selected:
            - true
            - false
            - true
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          properties:
            answer:
              $ref: '#/components/schemas/MultipleResponsesAnswer'
    TaskAspectsRequest:
      type: object
      properties:
        tenantId:
          type: string
        taskDefinition:
          $ref: '#/components/schemas/Task'
      description: Task aspects request.
      example:
        tenantId: tenant_123
        taskDefinition:
          id: task_waterloo
          problemStatement: When was the Battle of Waterloo?
          type: FREEFORM_TEXT
          sampleSolutions:
            - content: The Battle of Waterloo was in 1815.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
