Your first exercise

Four steps, in your own codebase. The snippets below are TypeScript, taken from the demo's server.ts and index.html; the Python, C# and PHP demos do the same thing with the same method names.

1. Create a session, server side

A session is one student's attempt at one exercise. You create it from your backend, never from the browser, because creating it needs your API key.

import { ApiClient } from '@algebrakit/sdk';

const client = new ApiClient('https://api.algebrakit.com', process.env.ALGEBRAKIT_API_KEY);

const response = await client.createSession({
  exercises: [{ exerciseId: 'cacd2924-d497-4a7c-85d7-bcb1256d7bf2', version: 'latest' }],
  apiVersion: 2,
});

const { sessionId, html } = response[0].sessions[0];

Keep the sessionId: it is how you read the marks back later, and how you tie the attempt to a student in your own database. The html is a snippet to drop into your page.

The exerciseId identifies an exercise authored in the Algebrakit CMS. You can also define an exercise in code instead of referencing one; see the exercise specification.

2. Put it in the page

The page needs three things: the proxy configuration, the widget script, and the html you just received.

<!-- Must be set BEFORE the widget script loads. -->
<script>
  AlgebraKIT = {
    config: {
      proxy: { url: '/proxy/algebrakit' }
    }
  };
</script>

<script src="https://widgets.algebrakit.com"></script>

<!-- The html returned by createSession -->
<div class="exercise-container">{{ EXERCISE_HTML }}</div>

Order matters: the configuration object has to exist before the script runs. Do not add async to the script tag, and never load it twice on one page.

3. Forward the widget's calls

The widget talks to Algebrakit while the student works: evaluating input, fetching hints, storing progress. Those calls go to your server first, which attaches the API key and passes them on. That is the whole reason the key stays out of the browser.

const PROXY_PREFIX = '/proxy/algebrakit';

// Anything under /proxy/algebrakit/* goes to the API with the key attached.
const upstream = await fetch('https://api.algebrakit.com' + req.url.substring(PROXY_PREFIX.length), {
  method: req.method,
  headers: {
    'Content-Type': req.headers['content-type'] || 'application/json',
    'x-api-key': API_KEY,
  },
  body: requestBody,
});

This is also where you decide who is allowed through: your proxy already knows which user is logged in, so it can refuse calls for sessions that do not belong to them. Set up the proxy covers this in full.

4. Read the marks back

const score = await client.getSessionScore({ sessionId, lockSession: false });

score.scoring.finished;      // has the student completed it
score.scoring.marksEarned;   // out of score.scoring.marksTotal
score.scoring.penalties;     // hints requested, maths errors made

Call this whenever your platform needs a result: when the student presses hand in, when a teacher opens a report, or on a schedule. Pass lockSession: true when the attempt is final and no further work should be accepted.

Treat this endpoint as the authoritative record. Learning events reach the browser first, so they are right for driving your UI, but the score comes from Algebrakit's own store and cannot be tampered with client side.

Optional: react as the student works

If you want to update your own interface while the exercise is in progress, subscribe to learning events:

AlgebraKIT.addExerciseListener(function (evt) {
  // evt.event is the event name, evt.sessionId the session it belongs to
  console.log(evt.event, evt);
});

Use it to enable a "next" button when exercise-finished fires, to drive your own hint button, or to record how a student worked. See Consume learning events.

Before you go to production

Use your own API key, from a free account or a commercial one, and keep it server side only.
Check the proxy authenticates the user. A proxy that forwards anything is an open door to your API key.
Pin an LTS version rather than tracking latest. See Releases and LTS.

What to read next points you at the rest of the documentation, depending on what you are building.