Taskbase API (0.9.0)

Here is the OpenAPI specification for our stable public endpoints.

Download OpenAPI description

specification.json

specification.yaml

Overview

URL https://redirect.taskbase.com/help-center

License Copyright Taskbase

Servers

Default server

https://api.taskbase.com/

Feedback

Endpoints for working with feedback.

Operations

Computes feedback for an existing task.

Request

This endpoint works for tasks that have already been registered.

Path

taskIdstringrequired

The ID of the task.

Bodyapplication/json

userIdstringrequired

By setting this field, you will link the answer to the provided learner identifier. Alternatively, you can use an anonymous identifier if preferred.

Example: "some_anonymous_id"

tenantIdstring

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 of type MISSING_PERMISSIONS will be returned.

Example: "product_123"

metaDataobject

The object containing metadata related to the learner interaction.

taskTypestringrequired

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"

Discriminator

answerobjectrequired

answer.contentstringrequired

The content submitted as the solution to the task.

Example: "The Battle of Waterloo was in 1815."

curl -i -X POST \
  'https://api.taskbase.com/tasks/${taskId}/feedback/compute' \
  -H 'Authorization: Bearer <YOUR_UUID_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "some_anonymous_id",
    "taskType": "FREEFORM_TEXT",
    "answer": {
      "content": "The Battle of Waterloo was in 1815."
    }
  }'

Responses

successful operation

Bodyapplication/json

userIdstringrequired

The user ID this feedback is meant for.

Example: "some_anonymous_id"

taskIdstringrequired

The task ID this feedback is meant for.

Example: "0Ihkl0CyzoWSjDm5F"

taskTypestringrequired

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"

Discriminator

metaDataobjectrequired

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.

metaData.taskActionstringrequired

The action that was performed on the task.

Enum"CREATED""UPDATED""UNCHANGED"

metaData.tenantIdstringrequired

metaData.taskLinkstringrequired

Deeplink to task in the Taskbase Cockpit.

resultobjectrequired

result.sampleSolutionobjectrequired

result.sampleSolution.contentstringrequired

A sample solution to the task.

Example: "The Battle of Waterloo was in 1815."

result.feedbackArray of objectsrequired

result.feedback[].correctnessstringrequired

The correctness of the learner's answer.

Enum"CORRECT""PARTIAL""WRONG""UNKNOWN"

result.feedback[].aspectsArray of objectsrequired

An array of Aspects that resulted in the given feedback.

result.feedback[].aspects[].namestringrequired

The Aspect name.

Example: "Present 3rd person singular of regular verbs."

result.feedback[].aspects[].descriptionstringrequired

The Aspect description.

Example: "A learner can correctly form the present 3rd person singular of regular verbs."

result.feedback[].aspects[].typestringrequired

Indicates whether an Aspect represents a misconception (wrong aspect) or a concept (correct aspect).

Enum"CONCEPT""MISCONCEPTION"

result.feedback[].aspects[].aspectGroupobject

The group to which the Aspect belongs.

result.feedback[].messagestring

The feedback message.

Example: "Indeed, the Battle of Waterloo was on Saturday, the 15th of June 1815"

result.feedback[].contextArray of objectsrequired

result.feedback[].context[].contentstringrequired

The content of this part of the answer, included for convenience. It can also be obtained from the answer using the offset and length.

Example: "was in 1815"

result.feedback[].context[].offsetintegerrequired

The position offset relative to the full answer.

Example: 23

result.feedback[].context[].lengthintegerrequired

The length of this part of the answer.

Example: 11

result.feedback[].topicobjectDeprecated

NOTE: This field is deprecated. Please use the aspects field below instead.

result.answerobjectrequired

result.answer.contentstringrequired

The content submitted as the solution to the task.

Example: "The Battle of Waterloo was in 1815."

result.allAspectsArray of objects(FreeformTextDetectedAspect)

An array of all detected Aspects for the given interaction.

Response

application/json

{
  "userId": "some_anonymous_id",
  "taskId": "0Ihkl0CyzoWSjDm5F",
  "taskType": "FREEFORM_TEXT",
  "metaData": {
    "taskAction": "CREATED",
    "tenantId": "string",
    "taskLink": "string"
  },
  "result": {
    "sampleSolution": { … },
    "feedback": [ … ],
    "answer": { … },
    "allAspects": [ … ]
  }
}

Computes feedback for the provided task and answer

Request

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.

Bodyapplication/json

userIdstringrequired

By setting this field, you will link the answer to the provided learner identifier. Alternatively, you can use an anonymous identifier if preferred.

Example: "some_anonymous_id"

tenantIdstring

Example: "product_123"

metaDataobject

The object containing metadata related to the learner interaction.

taskTypestringrequired

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"

Discriminator

taskDefinitionobjectrequired

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.

taskDefinition.idstringrequired

The task ID. This field should contain the task identifier used in the client's system.

Example: "your_id_as_string"

taskDefinition.problemStatementstringrequired

The problem statement of the task.

Example: "When was the Battle of Waterloo?"

taskDefinition.typestringrequired

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"

Discriminator

taskDefinition.titlestring

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"

taskDefinition.languagestring

The task language.

Default "EN_US"

Enum"DE_CH""DE_DE""EN_US""EN_UK""FR_FR""IT_IT""ES_ES"

taskDefinition.sampleSolutionsArray of objects

taskDefinition.contextstring

Context, such as background knowledge or additional information, required to solve the task.

Default ""

taskDefinition.resourceobject

The object containing information about the media file.

taskDefinition.sampleSolutionstringDeprecated

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.

Default ""

answerobjectrequired

answer.contentstringrequired

The content submitted as the solution to the task.

Example: "The Battle of Waterloo was in 1815."

curl -i -X POST \
  https://api.taskbase.com/feedback/compute \
  -H 'Authorization: Bearer <YOUR_UUID_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "some_anonymous_id",
    "taskType": "FREEFORM_TEXT",
    "taskDefinition": {
      "id": "your_id_as_string",
      "problemStatement": "When was the Battle of Waterloo?",
      "type": "FREEFORM_TEXT"
    },
    "answer": {
      "content": "The Battle of Waterloo was in 1815."
    }
  }'

Responses

successful operation

Bodyapplication/json

userIdstringrequired

The user ID this feedback is meant for.

Example: "some_anonymous_id"

taskIdstringrequired

The task ID this feedback is meant for.

Example: "0Ihkl0CyzoWSjDm5F"

taskTypestringrequired

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"

Discriminator

metaDataobjectrequired

metaData.taskActionstringrequired

The action that was performed on the task.

Enum"CREATED""UPDATED""UNCHANGED"

metaData.tenantIdstringrequired

metaData.taskLinkstringrequired

Deeplink to task in the Taskbase Cockpit.

resultobjectrequired

result.sampleSolutionobjectrequired

result.sampleSolution.contentstringrequired

A sample solution to the task.

Example: "The Battle of Waterloo was in 1815."

result.feedbackArray of objectsrequired

result.feedback[].correctnessstringrequired

The correctness of the learner's answer.

Enum"CORRECT""PARTIAL""WRONG""UNKNOWN"

result.feedback[].aspectsArray of objectsrequired

An array of Aspects that resulted in the given feedback.

result.feedback[].aspects[].namestringrequired

The Aspect name.

Example: "Present 3rd person singular of regular verbs."

result.feedback[].aspects[].descriptionstringrequired

The Aspect description.

Example: "A learner can correctly form the present 3rd person singular of regular verbs."

result.feedback[].aspects[].typestringrequired

Indicates whether an Aspect represents a misconception (wrong aspect) or a concept (correct aspect).

Enum"CONCEPT""MISCONCEPTION"

result.feedback[].aspects[].aspectGroupobject

The group to which the Aspect belongs.

result.feedback[].messagestring

The feedback message.

Example: "Indeed, the Battle of Waterloo was on Saturday, the 15th of June 1815"

result.feedback[].contextArray of objectsrequired

result.feedback[].context[].contentstringrequired

The content of this part of the answer, included for convenience. It can also be obtained from the answer using the offset and length.

Example: "was in 1815"

result.feedback[].context[].offsetintegerrequired

The position offset relative to the full answer.

Example: 23

result.feedback[].context[].lengthintegerrequired

The length of this part of the answer.

Example: 11

result.feedback[].topicobjectDeprecated

NOTE: This field is deprecated. Please use the aspects field below instead.

result.answerobjectrequired

result.answer.contentstringrequired

The content submitted as the solution to the task.

Example: "The Battle of Waterloo was in 1815."

result.allAspectsArray of objects(FreeformTextDetectedAspect)

An array of all detected Aspects for the given interaction.

Response

application/json

{
  "userId": "some_anonymous_id",
  "taskId": "0Ihkl0CyzoWSjDm5F",
  "taskType": "FREEFORM_TEXT",
  "metaData": {
    "taskAction": "CREATED",
    "tenantId": "string",
    "taskLink": "string"
  },
  "result": {
    "sampleSolution": { … },
    "feedback": [ … ],
    "answer": { … },
    "allAspects": [ … ]
  }
}

Aspects

Endpoints for working with Aspects.

Operations

Taskbase API (0.9.0)

Feedback

Computes feedback for an existing task.

Request

Responses

Was this helpful?

Computes feedback for the provided task and answer

Request

Responses

Was this helpful?

Aspects

Taskbase API (0.9.0)

Feedback

Computes feedback for an existing task.

RequestExpand all

Responses

Was this helpful?

Computes feedback for the provided task and answer

RequestExpand all

Responses

Was this helpful?

Aspects

Request

Request