openapi: 3.0.1
info:
  title: Taskbase API
  description: |

    Here is the OpenAPI specification for our stable public endpoints.
  version: 0.9.0
  contact:
    url: https://redirect.taskbase.com/help-center
    name: API Support
  x-logo:
    url: https://showroom.taskbase.com/assets/img/logos/logo.png
    altText: Taskbase
    href: https://taskbase.com
  license:
    name: Copyright Taskbase
    url: https://www.taskbase.com
servers:
  - url: https://api.taskbase.com
    description: Default server
tags:
  - name: Feedback
    description: Endpoints for working with feedback.
  - name: Aspects
    x-displayName: Aspects
    description: Endpoints for working with Aspects.
x-tagGroups:
  - name: Endpoints
    tags:
      - Feedback
      - Aspects
paths:
  /tasks:
    get:
      x-internal: true
      tags:
        - Tasks
      summary: Returns all task IDs for which feedback can be computed.
      description: |
        **TODO** write description
      operationId: getAllTasks
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - tenantId
                    - type
                  properties:
                    id:
                      type: string
                      description: The task ID for which feedback can be computed.
                    tenantId:
                      allOf:
                        - $ref: '#/components/schemas/TenantId'
                    type:
                      allOf:
                        - $ref: '#/components/schemas/TaskType'
      security:
        - BearerAuthentication: []
  /tasks/${taskId}/feedback/compute:
    post:
      tags:
        - Feedback
      summary: Computes feedback for an existing task.
      description: |
        This endpoint works for tasks that have already been registered.
      operationId: computeFeedbackByTaskId
      parameters:
        - in: path
          name: taskId
          schema:
            type: string
          required: true
          description: The ID of the task.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequestByTaskId'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feedback'
        '400':
          description: >-
            The request is malformed, possibly due to an invalid or missing
            authorization field or an incorrect schema in the request body.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        The user associated with the provided bearer token is
                        not authorized.
        '500':
          description: >-
            An internal server error occurred. While this error is unlikely, the
            message will include an identifier to help with quick
            troubleshooting.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        An error occurred while processing your request. It has
                        been logged with the ID 2b6b2818cc22fc4b.
      security:
        - BearerAuthentication: []
  /feedback/compute:
    post:
      tags:
        - Feedback
      summary: Computes feedback for the provided task and answer
      description: >
        This operation provides access to our formative feedback. The task
        included in the request is essential for context and must be provided
        with every request. This ensures synchronization and prevents issues
        where feedback might be based on an outdated version of the task.



        The `id` field in the task object is crucial for identifying answers
        associated with the same task. This field represents the task's
        identifier as defined in the client’s system.


        If the id remains the same across requests but other task fields change,
        the system updates the fields for the existing task 𝑡. Feedback is then
        generated based on previously submitted answers and feedback related to
        task 𝑡 (`*`). If the system has not seen the value of the `id` field
        before, a new task 𝑡′ is created. In this case, there are no existing
        answers or feedback linked to task 𝑡′.


        To avoid unintended behavior, only change the id field when creating a
        completely new task.



        (`*`) This applies only if the task types remain the same. If a request
        specifies a task type for t that differs from the type already
        associated with it from previous requests, an error will be returned.

        ---


        **Important note on task updates**: Whenever a task is updated in the
        client's system, it should be assumed that these changes affect the
        feedback. Therefore, we recommend the following actions to align with
        the changes: test the feedback after making changes; create new answers
        to reflect the updated task; and consider reassigning existing feedback
        for previous answers. Without these measures, the generated feedback may
        no longer be accurate.
      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: >-
            The request is malformed, possibly due to an invalid or missing
            authorization field or an incorrect schema in the request body.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        The user associated with the provided bearer token is
                        not authorized.
        '500':
          description: >-
            An internal server error occurred. While this error is unlikely, the
            message will include an identifier to help with quick
            troubleshooting.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        An error occurred while processing your request. It has
                        been logged with the ID 2b6b2818cc22fc4b.
      security:
        - BearerAuthentication: []
  /tasks/aspects/compute:
    post:
      tags:
        - Aspects
      summary: Returns all relevant Aspects for a given task.
      description: >
        This endpoint returns all relevant Aspects for a given task.


        **NOTE**: This endpoint is in the alpha stage and its structure may
        change.
      operationId: computeTaskAspects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskAspectsRequest'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Aspect'
        '400':
          description: >-
            The request is malformed, possibly due to an invalid or missing
            authorization field or an incorrect schema in the request body.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        The user associated with the provided bearer token is
                        not authorized.
        '500':
          description: >-
            An internal server error occurred. While this error is unlikely, the
            message will include an identifier to help with quick
            troubleshooting.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - example:
                      message: >-
                        An error occurred while processing your request. It has
                        been logged with the ID 2b6b2818cc22fc4b.
      security:
        - BearerAuthentication: []
components:
  schemas:
    TaskType:
      type: string
      enum:
        - FREEFORM_TEXT
        - IN_TEXT_FILL_IN_BLANKS
        - IN_TEXT_CHOICES
        - MULTIPLE_CHOICE
        - MULTIPLE_RESPONSES
      description: >-
        Defines the type of the task. Can be used by deserialization tools to
        instantiate the correct sub-type.
    FreeformTextTaskSpecific:
      type: object
      properties:
        sampleSolution:
          deprecated: true
          type: string
          default: ''
          description: >
            The single answer to the problem statement that is considered
            correct.


            **NOTE:** This field is deprecated and will eventually be removed in
            favor of the `sampleSolutions` array.
        sampleSolutions:
          type: array
          items:
            type: object
            required:
              - content
            properties:
              content:
                type: string
                description: An answer to the problem statement that is considered correct.
                example: 1815
        context:
          type: string
          default: ''
          description: >-
            Context, such as background knowledge or additional information,
            required to solve the task.
        resource:
          allOf:
            - $ref: '#/components/schemas/FreeformTextResource'
          description: A media file of the task.
    InTextFillInBlanksTaskSpecific:
      type: object
      required:
        - blanks
        - textWithBlanks
      properties:
        textWithBlanks:
          type: string
          description: >
            The text containing blanks that need to be filled in. A blank needs
            to be represented in-text via the following string: `"{--}"`.


            Example: `"The battle of Waterloo was in {--}. It was the last
            battle of {--}."`


            Additionally, placeholders should not be included in this field. If
            they are present in the text, ensure they are removed before making
            the request. Failure to do so may negatively affect the evaluation,
            which relies only on the sample solution.


            **Don't:** `"Tim is {--} (cook) pasta."`

            **Do:** `"Tim is {--} pasta."`
        blanks:
          type: array
          items:
            type: object
            required:
              - solutions
            properties:
              solutions:
                type: array
                items:
                  type: object
                  required:
                    - content
                  properties:
                    content:
                      type: string
                      description: |
                        A sample solution for the blank.
                      example: 1815
          description: >
            Context for the corresponding blank in the text. Each element in
            this array must map to the blank at the same index in the text.
            Therefore, the number of elements in the array must be equal to the
            number of blanks in the text.
    InTextChoicesTaskSpecific:
      type: object
      required:
        - textWithChoices
        - choices
      properties:
        textWithChoices:
          type: string
          description: |
            The text that includes the choices.
        choices:
          type: array
          description: |
            The choices for the text.
          items:
            type: object
            required:
              - indexOfSolution
              - options
              - solutions
            properties:
              options:
                type: array
                items:
                  $ref: '#/components/schemas/InTextChoiceOption'
    InTextChoiceOption:
      type: object
      required:
        - option
      properties:
        option:
          type: string
        isCorrect:
          type: boolean
    MultipleChoiceTaskSpecific:
      type: object
      required:
        - indexOfSolution
        - choices
      properties:
        choices:
          type: array
          description: |
            The option choices for the task.
          items:
            $ref: '#/components/schemas/MultipleChoiceOption'
        indexOfSolution:
          type: integer
          description: >
            The index of the correct option in the choices array, starting from
            0.
    MultipleChoiceOption:
      type: object
      required:
        - option
      properties:
        option:
          type: object
          required:
            - text
          properties:
            text:
              type: string
    MultipleResponsesTaskSpecific:
      type: object
      required:
        - indicesOfSolutions
        - choices
      properties:
        choices:
          type: array
          description: |
            The option choices for the task.
          items:
            $ref: '#/components/schemas/MultipleResponsesOption'
        indicesOfSolutions:
          type: array
          description: >
            The indices of the correct options in the choices array, starting
            from 0.
          items:
            type: integer
    MultipleResponsesOption:
      type: object
      required:
        - option
      properties:
        option:
          type: object
          required:
            - text
          properties:
            text:
              type: string
    Task:
      type: object
      required:
        - id
        - problemStatement
        - type
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/TaskId'
        problemStatement:
          type: string
          example: When was the Battle of Waterloo?
          description: The problem statement of the task.
        type:
          allOf:
            - $ref: '#/components/schemas/TaskType'
        title:
          type: string
          example: my_task_title
          description: >-
            The task title. If left blank, the `taskDefinition.id` will be used
            as the title during implicit task creation or update.
        language:
          type: string
          enum:
            - DE_CH
            - DE_DE
            - EN_US
            - EN_UK
            - FR_FR
            - IT_IT
            - ES_ES
          x-enum-varnames:
            - DE_CH
            - DE_DE
            - EN_US
            - EN_UK
            - FR_FR
            - IT_IT
            - ES_ES
          default: EN_US
          description: The task language.
      discriminator:
        propertyName: type
        mapping:
          FREEFORM_TEXT: '#/components/schemas/FreeformTextTask'
          IN_TEXT_FILL_IN_BLANKS: '#/components/schemas/InTextFillInBlanksTask'
          IN_TEXT_CHOICES: '#/components/schemas/InTextChoicesTask'
          MULTIPLE_CHOICE: '#/components/schemas/MultipleChoiceTask'
          MULTIPLE_RESPONSES: '#/components/schemas/MultipleResponsesTask'
    InTextFillInBlanksTask:
      allOf:
        - $ref: '#/components/schemas/Task'
        - $ref: '#/components/schemas/InTextFillInBlanksTaskSpecific'
    FreeformTextTask:
      allOf:
        - $ref: '#/components/schemas/Task'
        - $ref: '#/components/schemas/FreeformTextTaskSpecific'
    InTextChoicesTask:
      allOf:
        - $ref: '#/components/schemas/Task'
        - $ref: '#/components/schemas/InTextChoicesTaskSpecific'
    MultipleChoiceTask:
      allOf:
        - $ref: '#/components/schemas/Task'
        - $ref: '#/components/schemas/MultipleChoiceTaskSpecific'
    MultipleResponsesTask:
      allOf:
        - $ref: '#/components/schemas/Task'
        - $ref: '#/components/schemas/MultipleResponsesTaskSpecific'
    FreeformTextAnswer:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          example: The Battle of Waterloo was in 1815.
          description: The content submitted as the solution to the task.
    FreeformTextSampleSolution:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          example: The Battle of Waterloo was in 1815.
          description: A sample solution to the task.
    FreeformTextResource:
      type: object
      description: The object containing information about the media file.
      required:
        - type
        - format
        - src
      properties:
        type:
          type: string
          enum:
            - audio
          description: The supported media file type.
        format:
          type: string
          enum:
            - mp3
          description: The audio file format.
        src:
          type: string
          description: The URL that links to media for the target sentence.
    InTextFillInBlanksAnswer:
      type: object
      required:
        - blanks
      properties:
        blanks:
          type: array
          items:
            type: object
            required:
              - content
            properties:
              content:
                type: string
          description: >
            The answers for all blanks in the string. Use an empty string `""`
            if a blank is left empty.

            The length of this array must be equal to the length of the sample
            solution array.
    InTextFillInBlanksSampleSolution:
      type: object
      required:
        - blanks
      properties:
        blanks:
          type: array
          items:
            type: object
            required:
              - content
            properties:
              content:
                type: string
          description: A sample solution to the task.
    InTextChoicesAnswer:
      type: object
      required:
        - choices
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/InTextChoicesAnswerOption'
          description: >
            The answers for all choice placeholders in the string. Use an empty
            string `""` if nothing has been

            selected. The length of this array must be equal to the length of
            the sample solution array.
    InTextChoicesAnswerOption:
      type: object
      required:
        - content
      properties:
        content:
          type: string
    InTextChoicesSampleSolution:
      type: object
      required:
        - choices
      properties:
        choices:
          type: array
          items:
            type: object
            required:
              - content
            properties:
              content:
                type: string
            description: A sample solution to the task.
    MultipleChoiceAnswer:
      type: object
      required:
        - selectedIndex
      properties:
        selectedIndex:
          type: integer
          description: >-
            The index (starting from 0) of the selected option from the choices
            array in the `taskDefinition`, submitted as the answer to the task.
          example: 1
    MultipleChoiceSampleSolution:
      type: object
      required:
        - selectedIndex
      properties:
        selectedIndex:
          type: integer
          description: A sample solution to the task.
          example: 1
    MultipleResponsesAnswer:
      type: object
      required:
        - selected
      properties:
        selected:
          type: array
          description: >-
            The selected options from the choices array, submitted as the
            solution to the task. The length of this array needs to be equal to
            the length of the task's options array.
          items:
            type: boolean
          example:
            - true
            - null
            - false
    MultipleResponsesSampleSolution:
      type: object
      required:
        - selected
      properties:
        selected:
          type: array
          description: A sample solution to the task.
          items:
            type: boolean
          example:
            - true
            - true
            - false
    TaskAspectsRequest:
      type: object
      required:
        - tenantId
        - taskDefinition
      properties:
        tenantId:
          allOf:
            - $ref: '#/components/schemas/TenantId'
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/Task'
    UserId:
      type: string
      example: some_anonymous_id
      description: >
        By setting this field, you will link the answer to the provided learner
        identifier.

        Alternatively, you can use an anonymous identifier if preferred.
    TenantId:
      type: string
      example: product_123
      description: >
        The identifier of the tenant where the target task, specified in the
        taskDefinition, will be stored or searched for. If not provided the
        domain's default tenant will be used. Ensure that the API user has the
        necessary permissions on the target tenant to create or update a task.
        If not, an
        [error-response](http://localhost:60000/documentation#tag/error_response_model)
        of type `MISSING_PERMISSIONS` will be returned.
    TaskId:
      type: string
      example: your_id_as_string
      description: >-
        The task ID. This field should contain the task identifier used in the
        client's system.
    FeedbackRequestMetaData:
      type: object
      description: |
        The object containing metadata related to the learner interaction.
      properties:
        timeOnTask:
          type: integer
          example: 64
          description: >
            The time in seconds it takes the user to answer the task. While this
            field is not mandatory, it may eventually impact the learner's task
            recommendations. Hence, it is recommended to set and track this
            field.
        tryCount:
          type: integer
          example: 3
          description: >
            The number of attempts the learner has made, including the current
            request. This can be useful if the userId is not unique for privacy
            reasons or if not every attempt is sent via the API. Otherwise, the
            attempt count can be inferred from the number of API calls and is
            typically left empty.
    FeedbackRequestByTaskId:
      type: object
      required:
        - userId
        - taskType
      properties:
        userId:
          allOf:
            - $ref: '#/components/schemas/UserId'
        tenantId:
          allOf:
            - $ref: '#/components/schemas/TenantId'
        metaData:
          allOf:
            - $ref: '#/components/schemas/FeedbackRequestMetaData'
        taskType:
          allOf:
            - $ref: '#/components/schemas/TaskType'
      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'
    FeedbackRequest:
      type: object
      required:
        - taskType
        - userId
      properties:
        userId:
          allOf:
            - $ref: '#/components/schemas/UserId'
        tenantId:
          allOf:
            - $ref: '#/components/schemas/TenantId'
        metaData:
          allOf:
            - $ref: '#/components/schemas/FeedbackRequestMetaData'
        taskType:
          allOf:
            - $ref: '#/components/schemas/TaskType'
      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'
    InTextFillInBlanksFeedbackRequestSpecific:
      type: object
      required:
        - taskDefinition
        - answer
      properties:
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/InTextFillInBlanksTask'
            - type: object
              description: >
                The task definition for the `IN_TEXT_FILL_IN_BLANKS`-type task.


                **NOTE:** If the `type` field does not match in the UI
                documentation view, you may need to adjust it manually.
        answer:
          allOf:
            - $ref: '#/components/schemas/InTextFillInBlanksAnswer'
    InTextFillInBlanksFeedbackRequest:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - $ref: '#/components/schemas/InTextFillInBlanksFeedbackRequestSpecific'
    InTextFillInBlanksFeedbackRequestByTaskId:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          required:
            - answer
          properties:
            answer:
              allOf:
                - $ref: '#/components/schemas/InTextFillInBlanksAnswer'
    FreeformTextFeedbackRequestSpecific:
      type: object
      required:
        - answer
        - taskDefinition
      properties:
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/FreeformTextTask'
            - type: object
              description: >
                The task definition for the `FREEFORM_TEXT`-type task.


                **NOTE:** If the `type` field does not match in the UI
                documentation view, you may need to adjust it manually.
        answer:
          allOf:
            - $ref: '#/components/schemas/FreeformTextAnswer'
    FreeformTextFeedbackRequest:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - $ref: '#/components/schemas/FreeformTextFeedbackRequestSpecific'
    FreeformTextFeedbackRequestByTaskId:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          required:
            - answer
          properties:
            answer:
              allOf:
                - $ref: '#/components/schemas/FreeformTextAnswer'
    InTextChoicesFeedbackRequestSpecific:
      type: object
      required:
        - answer
        - taskDefinition
      properties:
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/InTextChoicesTask'
            - type: object
              description: >
                The task definition for the `IN_TEXT_CHOICES`-type task.


                **NOTE:** If the `type` field does not match in the UI
                documentation view, you may need to adjust it manually.
        answer:
          allOf:
            - $ref: '#/components/schemas/InTextChoicesAnswer'
    InTextChoicesFeedbackRequest:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - $ref: '#/components/schemas/InTextChoicesFeedbackRequestSpecific'
    InTextChoicesFeedbackRequestByTaskId:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          required:
            - answer
          properties:
            answer:
              allOf:
                - $ref: '#/components/schemas/InTextChoicesAnswer'
    MultipleChoiceFeedbackRequestSpecific:
      type: object
      required:
        - answer
        - taskDefinition
      properties:
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/MultipleChoiceTask'
            - type: object
              description: >
                The task definition for the `MULTIPLE_CHOICE`-type task.


                **NOTE:** If the `type` field does not match in the UI
                documentation view, you may need to adjust it manually.
        answer:
          allOf:
            - $ref: '#/components/schemas/MultipleChoiceAnswer'
    MultipleChoiceFeedbackRequest:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - $ref: '#/components/schemas/MultipleChoiceFeedbackRequestSpecific'
    MultipleChoiceFeedbackRequestByTaskId:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          required:
            - answer
          properties:
            answer:
              allOf:
                - $ref: '#/components/schemas/MultipleChoiceAnswer'
    MultipleResponsesFeedbackRequestSpecific:
      type: object
      required:
        - answer
        - taskDefinition
      properties:
        taskDefinition:
          allOf:
            - $ref: '#/components/schemas/MultipleResponsesTask'
            - type: object
              description: >
                The task definition for the `MULTIPLE_RESPONSES`-type task.


                **NOTE:** If the `type` field does not match in the UI
                documentation view, you may need to adjust it manually.
        answer:
          allOf:
            - $ref: '#/components/schemas/MultipleResponsesAnswer'
    MultipleResponsesFeedbackRequest:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequest'
        - $ref: '#/components/schemas/MultipleResponsesFeedbackRequestSpecific'
    MultipleResponsesFeedbackRequestByTaskId:
      allOf:
        - $ref: '#/components/schemas/FeedbackRequestByTaskId'
        - type: object
          required:
            - answer
          properties:
            answer:
              allOf:
                - $ref: '#/components/schemas/MultipleResponsesAnswer'
    Correctness:
      type: string
      enum:
        - CORRECT
        - PARTIAL
        - WRONG
        - UNKNOWN
      description: The correctness of the learner's answer.
    Topic:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The topic name.
    Aspect:
      type: object
      required:
        - name
        - description
        - type
      properties:
        name:
          type: string
          example: Present 3rd person singular of regular verbs.
          description: The Aspect name.
        description:
          type: string
          example: >-
            A learner can correctly form the present 3rd person singular of
            regular verbs.
          description: The Aspect description.
        type:
          type: string
          enum:
            - CONCEPT
            - MISCONCEPTION
          description: >-
            Indicates whether an Aspect represents a misconception (wrong
            aspect) or a concept (correct aspect).
        aspectGroup:
          type: object
          description: The group to which the Aspect belongs.
          required:
            - name
          properties:
            name:
              type: string
              description: The name of the Aspect group.
              example: Grammar
            description:
              type: string
              description: The description of the Aspect group.
              example: >-
                Grammatical concepts, such as conjugation, tenses, and
                conditionals.
    FeedbackItem:
      type: object
      required:
        - correctness
        - aspects
      properties:
        correctness:
          allOf:
            - $ref: '#/components/schemas/Correctness'
        topic:
          allOf:
            - $ref: '#/components/schemas/Topic'
          deprecated: true
          description: >
            **NOTE:** This field is deprecated. Please use the `aspects` field
            below instead.
        aspects:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Aspect'
          description: An array of Aspects that resulted in the given feedback.
        message:
          type: string
          example: >-
            Indeed, the Battle of Waterloo was on Saturday, the 15th of June
            1815
          description: The feedback message.
    InTextFillInBlanksContext:
      required:
        - content
        - index
      properties:
        content:
          type: string
          example: '1815'
          description: >-
            The content of this specific blank, included for convenience. It can
            also be obtained through the index from the answer array.
        index:
          type: integer
          example: 0
          description: The index of this specific blank.
      description: |
        The context indicates which part of the answer this feedback applies to.
        If the array is empty, the feedback applies to the entire answer.
    InTextFillInBlanksDetectedAspect:
      required:
        - aspect
        - context
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/InTextFillInBlanksContext'
    InTextFillInBlanksFeedbackItem:
      allOf:
        - $ref: '#/components/schemas/FeedbackItem'
        - type: object
          required:
            - context
          properties:
            context:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/InTextFillInBlanksContext'
    FreeformTextContext:
      required:
        - content
        - offset
        - length
      properties:
        content:
          type: string
          example: was in 1815
          description: >-
            The content of this part of the answer, included for convenience. It
            can also be obtained from the answer using the offset and length.
        offset:
          type: integer
          example: 23
          description: The position offset relative to the full answer.
        length:
          type: integer
          example: 11
          description: The length of this part of the answer.
      description: |
        The context indicates which part of the answer this feedback applies to.
        If the array is empty, the feedback applies to the entire answer.
    FreeformTextDetectedAspect:
      required:
        - aspect
        - context
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/FreeformTextContext'
    FreeformTextFeedbackItem:
      allOf:
        - $ref: '#/components/schemas/FeedbackItem'
        - type: object
          required:
            - context
          properties:
            context:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/FreeformTextContext'
    InTextChoicesContext:
      required:
        - content
        - index
      properties:
        content:
          type: string
          example: '1815'
          description: >-
            The content of this specific choice, included for convenience. It
            can also be obtained through the index from the answer array.
        index:
          type: integer
          example: 0
          description: The index of this specific blank.
      description: |
        The context indicates which part of the answer this feedback applies to.
        If the array is empty, the feedback applies to the entire answer.
    InTextChoicesDetectedAspect:
      required:
        - aspect
        - context
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/InTextChoicesContext'
    InTextChoicesFeedbackItem:
      allOf:
        - $ref: '#/components/schemas/FeedbackItem'
        - type: object
          required:
            - context
          properties:
            context:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/InTextChoicesContext'
    MultipleChoiceContext:
      required:
        - index
        - selected
      properties:
        index:
          type: integer
          example: 0
          description: The index of this specific option.
        selected:
          type: boolean
          example: true
          description: Whether this specific option was selected.
    MultipleChoiceDetectedAspect:
      required:
        - aspect
        - context
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/MultipleChoiceContext'
    MultipleChoiceFeedbackItem:
      allOf:
        - $ref: '#/components/schemas/FeedbackItem'
        - type: object
          required:
            - context
          properties:
            context:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/MultipleChoiceContext'
    MultipleResponsesContext:
      required:
        - index
      properties:
        index:
          type: integer
          example: 0
          description: The index of this specific option.
        selected:
          type: boolean
          example: true
          description: >-
            Whether this specific option was selected as true or false. If
            neither was selected, this is null.
    MultipleResponsesDetectedAspect:
      required:
        - aspect
        - context
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        context:
          $ref: '#/components/schemas/MultipleResponsesContext'
    MultipleResponsesFeedbackItem:
      allOf:
        - $ref: '#/components/schemas/FeedbackItem'
        - type: object
          required:
            - context
          properties:
            context:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/MultipleResponsesContext'
    AspectReponse:
      type: object
      required:
        - aspects
      properties:
        aspects:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Aspect'
          description: An array of Aspects that resulted in the given feedback.
    Feedback:
      type: object
      required:
        - userId
        - taskId
        - taskType
        - metaData
      properties:
        userId:
          type: string
          example: some_anonymous_id
          description: The user ID this feedback is meant for.
        taskId:
          type: string
          example: 0Ihkl0CyzoWSjDm5F
          description: The task ID this feedback is meant for.
        taskType:
          allOf:
            - $ref: '#/components/schemas/TaskType'
        metaData:
          type: object
          description: >
            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.
          required:
            - taskAction
            - tenantId
            - taskLink
          properties:
            taskAction:
              type: string
              enum:
                - CREATED
                - UPDATED
                - UNCHANGED
              description: |
                The action that was performed on the task.
            tenantId:
              type: string
            taskLink:
              type: string
              description: |
                Deeplink to task in the Taskbase Cockpit.
      discriminator:
        propertyName: taskType
        mapping:
          FREEFORM_TEXT: '#/components/schemas/FreeformTextFeedback'
          IN_TEXT_FILL_IN_BLANKS: '#/components/schemas/InTextFillInBlanksFeedback'
          IN_TEXT_CHOICES: '#/components/schemas/InTextChoicesFeedback'
          MULTIPLE_CHOICE: '#/components/schemas/MultipleChoiceFeedback'
          MULTIPLE_RESPONSES: '#/components/schemas/MultipleResponsesFeedback'
    InTextFillInBlanksFeedback:
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          required:
            - result
          properties:
            result:
              type: object
              required:
                - sampleSolution
                - feedback
                - answer
              properties:
                sampleSolution:
                  allOf:
                    - $ref: '#/components/schemas/InTextFillInBlanksSampleSolution'
                feedback:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/InTextFillInBlanksFeedbackItem'
                answer:
                  allOf:
                    - $ref: '#/components/schemas/InTextFillInBlanksAnswer'
                allAspects:
                  type: array
                  items:
                    $ref: '#/components/schemas/InTextFillInBlanksDetectedAspect'
                  description: An array of all detected Aspects for the given interaction.
    FreeformTextFeedback:
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          required:
            - result
          properties:
            result:
              type: object
              required:
                - sampleSolution
                - feedback
                - answer
              properties:
                sampleSolution:
                  allOf:
                    - $ref: '#/components/schemas/FreeformTextSampleSolution'
                feedback:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/FreeformTextFeedbackItem'
                answer:
                  allOf:
                    - $ref: '#/components/schemas/FreeformTextAnswer'
                allAspects:
                  type: array
                  items:
                    $ref: '#/components/schemas/FreeformTextDetectedAspect'
                  description: An array of all detected Aspects for the given interaction.
    InTextChoicesFeedback:
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          required:
            - result
          properties:
            result:
              type: object
              required:
                - sampleSolution
                - feedback
                - answer
              properties:
                sampleSolution:
                  allOf:
                    - $ref: '#/components/schemas/InTextChoicesSampleSolution'
                feedback:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/InTextChoicesFeedbackItem'
                answer:
                  allOf:
                    - $ref: '#/components/schemas/InTextChoicesAnswer'
                allAspects:
                  type: array
                  items:
                    $ref: '#/components/schemas/InTextChoicesDetectedAspect'
                  description: An array of all detected Aspects for the given interaction.
    MultipleChoiceFeedback:
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          required:
            - result
          properties:
            result:
              type: object
              required:
                - sampleSolution
                - feedback
                - answer
              properties:
                sampleSolution:
                  allOf:
                    - $ref: '#/components/schemas/MultipleChoiceSampleSolution'
                feedback:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/MultipleChoiceFeedbackItem'
                answer:
                  allOf:
                    - $ref: '#/components/schemas/MultipleChoiceAnswer'
                allAspects:
                  type: array
                  items:
                    $ref: '#/components/schemas/MultipleChoiceDetectedAspect'
                  description: An array of all detected Aspects for the given interaction.
    MultipleResponsesFeedback:
      allOf:
        - $ref: '#/components/schemas/Feedback'
        - type: object
          required:
            - result
          properties:
            result:
              type: object
              required:
                - sampleSolution
                - feedback
                - answer
              properties:
                sampleSolution:
                  allOf:
                    - $ref: '#/components/schemas/MultipleResponsesSampleSolution'
                feedback:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/MultipleResponsesFeedbackItem'
                answer:
                  allOf:
                    - $ref: '#/components/schemas/MultipleResponsesAnswer'
                allAspects:
                  type: array
                  items:
                    $ref: '#/components/schemas/MultipleResponsesDetectedAspect'
                  description: An array of all detected Aspects for the given interaction.
    ErrorType:
      type: string
      description: >-
        Possible errors the API may return. For more details, refer to the
        [error table](#section/Error-Types).
      enum:
        - REQUEST_SCHEMA_MALFORMED
        - INVALID_TOKEN
        - MISSING_PERMISSIONS
        - INVALID_PARAMETER
        - WRONG_TASK_TYPE_FOR_UPSERT
        - INTERNAL
    ErrorResponse:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
          description: >-
            Contains more detailed information about the root cause of the
            problem.
          example: computeFeedback.answer.text must not be null.
        type:
          allOf:
            - $ref: '#/components/schemas/ErrorType'
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
      bearerFormat: UUID
      description: >
        To authenticate with this API, use an API token that you can generate in
        the Taskbase Tool.

        You must be logged in as a user with the appropriate permissions to
        access the API. If you don't have access, please contact [Support]
        (https://www.taskbase.com/contact).


        We use the [Bearer
        Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/)
        scheme with UUIDs as tokens. Place the token inside the `Authorization`
        header as follows:


        ```bash

        Authorization: Bearer <token>

        ```
