Web Service - Overview

This page describes Algebrakit's web service API.

You call the API through JSON POST, encoding parameters as a JSON object in the message body. Choose the endpoint closest to your location:

Ireland: https://api.algebrakit.com
Singapore: https://prod.api.sg-1.algebrakit.com

Note: Make sure you use the same location to load the frontend.

Every request must include an X-API-KEY header containing the unique API key associated with your account.

URL	Description
/session/create	Create a new interaction from an Exercise Definition or the ID of a predefined exercise in the CMS.
/session/retrieve	Create a new interaction from an Exercise Definition or the ID of a predefined exercise in the CMS.
/session/solution	Get the worked solution for an exercise or an existing session.
/session/results	Returns information contained in the session, such as scoring and the students‘ actions (incl. evaluation results).
/session/score	Calculate scoring for a session.
/sessions/lock	Lock or unlock sessions for student input.
/exercise/generate	Generate non-random instances for a randomised exercise.
/exercise/published-info	Get general information about an exercise in Algebrakit’s CMS, such as name, interaction type, and the number of difficulty levels.
/exercise/validate	Retrieve information about an exercise and perform some validation.

Create session

Create new sessions for the (possibly randomized) Algebrakit exercises. You can create multiple sessions in one call to save round trips to Algebrakit’s web service. The response contains a unique session ID for each session. The reply also contains the optimized HTML code to create and initialize the web component for each session. You can insert this HTML in your web page at the appropriate location.

Endpoint: /session/create

Request Body

{
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
      sessionId?: <string>
      level?: <int>
      nr?: <int>
   }]
   scoringModel?: <string> 
   assessmentMode?: <boolean>
   requireLockForSolution?: <boolean>
   apiVersion: 2
}

Property	Description
`exerciseId`	ID of the exercise in the CMS. Either `exerciseId`, `exerciseSpec`, or `sessionId` is required.
`version`	The published version number of the exercise (number) or 'latest' (default), indicating the current version in the CMS.
`exerciseSpec`	Exercise Definition of the exercise. Either `exerciseId`, `exerciseSpec`, or `sessionId` is required.
`sessionId`	ID of an existing exercise session. Except for random exercises, the behavior is the same as for `exerciseId`. Using `exerciseId` on random exercises generates a new random instance of the exercise. Using `sessionId` generates a new session for the same random exercise. Either `exerciseId`, `exerciseSpec`, or `sessionId` is required
`level`	Optional. Difficulty level for the exercise. Applicable for randomized exercise arrangements, which generally offer multiple levels of difficulty. The default value is 0, which represents the lowest level. You can get the number of difficulty levels in the exercise from /exercise-info.
`nr`	Optional. Number of sessions to generate for this exercise. Only relevant for randomized exercises. The default value is 1.
`scoringModel`	Optional. Reference to a predefined scoring model for the exercise. If given, Algebrakit calculates the total marks and the marks earned based on the evaluations of the student's input and taking into account errors and hint requests. Algebrakit will use a standard scoring model that awards one mark to each interaction if omitted. See scoring for more information.
`requireLockForSolution`	Optional. If `true` (default), prevents anyone from obtaining the solution to this exercise before the session is locked.
`assessmentMode`	Optional. Setting this option to `true` turns off the step-by-step evaluation, hints, and feedback for the student.
`apiVersion`	Required. Always 2.

Output

The response contains the following session results for each element of the input array exercises.

[{
   success: <boolean>
   msg?: <string>
   sessions: [{
     success: <boolean>
     msg?: <string>
     sessionId: <string>
     html: <string>
     marksTotal: <number>
     type: 'SINGLE' | 'COMPOUND'
     interactions: {id => <InteractionDescription>}
   }]
}]

InteractionDescription = {
   type: <string>
   marks: <number>
   scorable?: <boolean>
}

Property	Description
`success`	Indicates if creating of the session succeeded
`msg`	If creating the session was unsuccessful, information about the error.
`sessionId`	A unique ID for this session.
`html`	Optimized html code to create the appropriate web component. This html code already contains the initialization data required by the web component for optimal performance.
`type`	`COMPOUND` if the exercise has multiple questions (a, b, c, etc). Otherwise `SINGLE`.
`marksTotal`	The total number of marks that can be earned with this exercise.
`interactions`	Information about each interaction.

Retrieve session

Returns the same session information produced by /session/create without creating a new session. This endpoint can be helpful to efficiently restore a webpage with existing Algebrakit exercises, including a student's previous input.

Note that restoring an existing exercise can be done without using this endpoint, simply by the akit-exercise or akit-interaction web components:

  <akit-exercise session-id="..."></akit-exercise>

The web component will retrieve all needed information (question type, learning events, etc) from the server. However, this roundtrip impacts page load time, especially if multiple exercises are on the page. The /session/retrieve endpoint lets you obtain optimized HTML code for multiple sessions in one call. Inserting this optimized HTML into the webpage prevents a server roundtrip per exercise and allows the exercises to show instantly.

Endpoint: /session/retrieve

Request Body

{
   sessionIds: <string>[]
}

Property	Description
`sessionIds`	Array of session IDs to retrieve.

Output

See /session/create.

Generate exercise

Generate nonrandom Exercise Definitions from randomized exercises. With these Exercise Definitions, you can repeatedly create new sessions using endpoint /session/create. A use case is to let an author define a test from a generated list of exercises. The Exercise Definitions of the chosen exercises can then be stored and used repeatedly.

To save round trips to Algebrakit’s web service, you can create multiple instances for randomized exercises in one call.

Endpoint: /exercise/generate

Request body

{
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
      level?: <int>
      nr?: <int>
   }]
   apiVersion: 2
}

Property	Description
`exerciseId`	ID of the exercise in the CMS. Either `exerciseId` or `exerciseSpec` is required.
`version`	The published version number of the exercise (number) or 'latest' (default). The latter refers to the current version of the exercise.
`exerciseSpec`	Exercise Definition of the exercise. Either `exerciseId` or `exerciseSpec` is required.
`level`	Optional. Difficulty level for the exercise. Applicable for randomized exercise arrangements, which generally offer multiple levels of difficulty. The default value is 0, which represents the lowest level. You can get the number of difficulty levels for the exercise from /exercise-info.
`nr`	Optional. Number of sessions to generate for this exercise. Only relevant for randomized exercises. Default value is 1.
`apiVersion`	Required. Always 2.

Output

The response contains the generated exercises for each element of the input array exercises.

[{
   success: <boolean>
   msg?: <string>
   instances: [{
     success: <boolean>
     msg?: <string>
     exerciseSpec: <Exercise>
     view: <ExerciseView>
   }]
}]

Property	Description
`success`	Indicates if generating the nonrandom exercise succeeded.
`msg`	If generating the nonrandom exercise was unsuccessful, information about the error.
`view`	Information relevant for display in the front end, such as instruction text, assignment expression, and required buttons for the formula editor.
`exerciseSpec`	The generated Exercise Definition object.

Get solution

Get the worked solutions for the given sessions. The reply also contains the optimized html code to create and initialize the correct web component for this exercise. You can insert this html in your web page at the appropriate location.

Endpoint: /session/solution

Request body

{
   ids: [<string>]
}

Property	Description
`ids`	Session IDs of the desired sessions.

Output

For each session, the following results.

[{
   success: <boolean>
   msg?: <string>
   sessionId: <string>
   type: <string>
   html: <string>
   }]
}]

Property	Description
`success`	Indicates if creating the solution for this session succeeded.
`msg`	If creating the solution was not successful, information about the error.
`sessionId`	The ID of the session that corresponds to this solution.
`html`	Optimised html code to create the appropriate web component. This html code already contains the initialization data required by the web component for optimal performance.

Get score

Perform a final evaluation for all interactions in this exercise (if necessary) and retrieve the session results. You can optionally lock the session to prevent any further modifications.

Endpoint: /session/score

Note: Ensure no evaluation events are ongoing when retrieving the score. Learning platforms that use javascript to submit a question should wait before requesting the score.

  await akitExercise.submit(); // wait until the Promise returned by submit() resolves
  // Evaluation is done. It is now safe to retrieve the score

Request Body

{
   sessionId: <string>
   lockSession?: <boolean>
}

Property	Description
`sessionId`	ID of the session.
`lockSession`	Set to `true` to reject future events (evaluation, hint) on this session. Note that it is impossible to unlock the session again.

Output

An exercise can consist of multiple questions (like questions a, b, c, etc.), each containing one or more interactions.

{
   scoring: <ScoringResult>
   questions: [{
      id: <string>
      scoring: <ScoringResult>
      interactions: <InteractionResult>[]
   }]
   tagDescriptions: {<string> : <SkillTagDescription>}
}

<InteractionResult> = {
   id: <string>
   type: <string>
   status: <EvaluationStatus>
   progress: <float>
   scoring: <ScoringResult>
   tags: <SkillTag>[]
   events: <EventData>[]
}

<EventData> =
    {
      event = 'EVALUATE' | 'HINT' | 'GIVEUP'
      timestamp: <long>
      tags: <SkillTag>[]
      annotations: Annotation[]

      //if event  == 'EVALUATE':
      exerciseStatus: <ExerciseStatus>
      inputStatus: <ExpressionStatus> 
      progress: <float> 
    }


<WKDescription> = {
    headLine: ContentElement[];
    subLine?: ContentElement[];
}

<ScoringResult> =
    {
        finished: <boolean>
        marksTotal: <float>
        marksEarned: <float>
        penalties?: {
            hintsRequested: <int>
            mathErrors: <int>
            notationErrors: <int>
        }
    }

<SkillTag> = 
  {
     id: <string>
     source: 'ERROR_FEEDBACK' | 'HINT' | 'FINISHED_STEP'
     weight: <float>
     errors?: <string>[]
  }

<SkillTagDescription> = 
  {
     id: <string>
     descr: {lang: <string>}
     stepType: "STRATEGY" | "ALGEBRA" | "CALCULATE" | "ROUND" | "CONCEPT"
     errors?: <ErrorTag>
  }

<ErrorTag> =
  {
     id: <string>
     descr: {lang: <string>}
     type: <ErrorType>[]
  }

<ErrorType> = "MISCONCEPTION" | "MISTAKE"

<Annotation> =
  {
    type: 'HINT' | 'ERROR_FEEDBACK' | 'INPUT_EXPRESSION'
    main?: ContentElement[];
    sub?: ContentElement[];
    expr?: ContentElement[];
  }

<ContentElement> = {
   mimeType: <string>
   content: <string>
}

<ExerciseStatus> = {
   "FINISHED" | "CORRECT" | "ERROR" | "VIRGIN" | "UNKNOWN"
}

<ExpressionStatus> = 
   'FINISHED' | 'CORRECT' | 'ERROR' | 'NO_MATCH' | 
   'PARSE_ERROR' | 'TRUE_EXPRESSION' | 'FALSE_EXPRESSION'

The output contains the following properties:

Property	Description
`scoring`	The total marking for this exercise, based on the results of all interactions.
`questions`	The total marking for each question. Questions are the parts of an exercise, indexed by a, b, c, etc.
`tagDescriptions`	A description of the skills identified in this exercise. The IDs of these tags occur in the results of the various events. You can find more information about detecting mathematical skills here.

The properties of a single interaction are:

Property	Description
`id`	The interaction's unique id, or 'ref-id', in this exercise.
`type`	The interaction type.
`events`	An array containing information for every evaluation or hint.
`scoring`	Contains the calculated marking for this interaction based on the evaluations, the hints, and the scoring model.
`progress`	Indicating what percentage of the exercise was completed.
`tags`	A list of tags identifying mathematical skills related to this session. The `id` in each tag refers to a more detailed description of the skill, which you can find in `tagDescriptions`. You can find more information about detecting mathematical skills here

The properties of an evaluation event are:

Property	Description
`exerciseStatus`	Overall status of the exercise: `FINISHED` if the question is completed successfully, `CORRECT` if the question contains valid input but is incomplete, `VIRGIN` if no work was done, `ERROR` if the last evaluation contained an error.
`inputStatus`	Evaluation class of the student input. See the table below for more information
`progress`	Indicating what percentage of the exercise was completed.
`tags`	A list of tags identifying mathematical skills related to this event. The `id` in each tag refers to a more detailed description of the skill, which you can find in `tagDescriptions`. You can find more information about detecting mathematical skills here.
`annotations`	Textual information about this event, such as error feedback, hint text, or input expression.

Textual information generally consists of text and math elements and is encoded as a list of ContentElement objects. Algebrakit offers two ways to convert this content into HTML; see AlgebraKIT.elements2HTML and akit-content-view.

Scoring results are summarized per interaction, per question, and for the whole exercise.

Property	Description
`finished`	Indicates if the student completed the exercise, question, or interaction successfully.
`marksTotal`	The total number of marks the student can earn for this interaction, question, or exercise.
`marksEarned`	The total number of marks that the student got for this interaction, question, or exercise.
`penalties`	Only present on the interaction level. It contains some extra information that explains the scoring for this interaction.

The property inputStatus can have the following values:

Value	Description
`FINISHED`	The input is accepted as the final answer to the question.
`CORRECT`	The input is a correct intermediate step but not the final answer.
`ERROR`	The input is incorrect, and Algebrakit has diagnosed an error.
`NO_MATCH`	Algebrakit could not relate the input to any solution step for this question. The input is probably false.
`PARSE_ERROR`	The input is not a valid mathematical expression.
`TRUE_EXPRESSION`	The input is a correct expression, such as 2x+3x=5x, but Algebrakit could not relate the input to any solution step for this question.
`FALSE_EXPRESSION`	The input is incorrect, such as 2+3=6.

Get results

Retrieve all student actions for the given session, including evaluation results. For example, you can use this information to calculate a student's score based on your scoring scheme. The output is similar to the response of Get score.

Endpoint: /session/result

Lock sessions

Lock or unlock a session. A locked session does not accept new inputs from a student. This functionality is mainly intended for assessments to guarantee nobody changes the results afterward.

There are two types of lock actions. You can later undo a LOCK action with an UNLOCK action. A FINALIZE action locks a session forever.

You can lock or unlock a batch of sessions in a single call.

Endpoint: /sessions/lock

Request Body

{
   action: 'LOCK' | 'UNLOCK' | 'FINALIZE'
   sessionIds: <string>[]
}

Property	Description
`action`	'LOCK': Apply a reversible lock; 'UNLOCK': Unlock a session that was locked with 'LOCK'; 'FINALIZE': Lock the session indefinitely.
`sessionIds`	Array of session IDs to lock or unlock.

Exercise info

Retrieve information about an exercise in Algebrakit's CMS, such as available versions, the structure, and the change history.

Endpoint: /exercise/published-info

Request Body

{
   id: <string>
}

Property	Description
`id`	ID of the exercise.

Output

Information about the structure of the exercise.

{
    commitHistory: CommitData[];
    id: string;
    publishedVersions: <PubVersionInfo>[];
    courseName: string;
    type: string;
}

Property	Description
`id`	The exercise ID
`type`	`regular exercise` if the question is defined by an Exercise Specification (default), `single reference` if the question is a reference to a question in the question library, `arrangement exercise` if the question refers to multiple questions in the question library.

<PubVersionInfo> = {
    name: string;
    majorVersion: number | 'latest';
    minorVersion: number;
    metadata: {[key: string]: string};
    numberOfLevels?: number;
    interactions: <InteractionInfo>[];
    resources: <ResourceInfo>[];
}

<CommitData> = {
    versionNumber: string;
    commitDate: Date;
    commitMessage: string;
    authorUsername: string
}

<InteractionInfo> = {
    block: string;
    refId: string;
    type: <QuestionType>;
    refName: string
}

<ResourceInfo> = {
    refId: string;
    type: string;
    refName: string
}

<QuestionType> = {
   MULTISTEP, 
   FILL_IN_THE_BLANKS, 
   MATH_TABLE, 
   MODEL_METHOD,
   ARITHMETIC,   //Written Arithmetic
   OPEN_ANSWER, 
   CHOICE, 
   STATISTICS,   //Data Analysis
   GEOMETRY,     //Geometry and Graphs
   NUMBER_LINE 
}

Validate exercise

This endpoint checks whether an exercise is valid (i.e., that it runs) and to obtain general information.

Endpoint: /exercise/validate

Request body

{ 
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
}

Property	Description
`exerciseId`	ID of the exercise in the CMS. Either `exerciseId` or `exerciseSpec` is required.
`version`	The published version number of the exercise (number) or 'latest' (default). The latter refers to the current version of the exercise.
`exerciseSpec`	An exercise specification as obtained from the exercise authoring tool

Output

{
   valid: <boolean>
   msg?: <string>
   marks: <number>
   random: <boolean>
   interactions: {[refId: string]:InteractionInfo}
]

InteractionInfo = {
   type: <string>
   marks: <number>
}

Property	Description
`valid`	If `false`, this exercise has a problem and is not suitable to create sessions.
`msg`	A description of the problem in case the exercise is not valid
`marks`	The total number of marks for this exercise
`random`	Indicates whether this exercise is randomized or not
`interactions`	A map with information on the interactions in the exercise. The key is the unique ID of the interaction.