Mastery API: BKT State and Heatmaps per Student

The Mastery API exposes the Bayesian Knowledge Tracing (BKT) state for each student across every curriculum topic they have attempted. Use these endpoints to build mastery dashboards, Student × Unit heatmaps, per-student drilldowns, and adaptive exercise recommendations driven by IRT Fisher information. All mastery records are updated automatically by POST /attempts — this API is read-only.

GET /mastery/:studentId

Retrieve per-topic BKT mastery state for a single student across all topics they have ever attempted — regardless of course. Each record includes the current pKnown probability and the topic code and name. GET /mastery/:studentId

Requires a valid JWT. Teachers typically call this scoped to a specific student; the student-facing app calls it with the authenticated student’s own ID.

Path parameters

studentId

string

required

The student’s profile UUID.

Response `200`

Returns an array of MasteryState objects — one per topic the student has attempted.

[
  {
    "studentId": "stu_abc123",
    "topicCode": "T-SUB-BORROW",
    "topicName": "Resta con préstamo",
    "pKnown": 0.68
  }
]

studentId

string

The student UUID.

topicCode

string

The curriculum topic code (e.g. T-SUB-BORROW).

topicName

string

Human-readable topic name in Spanish (e.g. Resta con préstamo).

pKnown

number

Current BKT probability of mastery — a value between 0 and 1. Values above 0.95 are conventionally considered mastered.

Example

curl https://api.innova.app/mastery/stu_abc123 \
  -H "Authorization: Bearer <token>"

GET /mastery/course/:courseId

Full mastery summary for every active student enrolled in a course. Returns the live-topic BKT state per student, their last 20 attempts, and a ranked error-frequency breakdown. Use this to drive the teacher’s class-level mastery dashboard. GET /mastery/course/:courseId

Topics are derived from the canonical taxonomy (Domain → Subdomain), not a fixed list. Only subdomains that have real signal in this course (a classified attempt or a BKT record) are included, so new guides surface new subdomains automatically.

Path parameters

courseId

string

required

UUID of the course.

Response `200`

Array of CourseStudentMasteryView objects — one per active enrollment, sorted by join date.

studentId

string

Student profile UUID.

displayName

string

Resolved display name. Falls back to the email username prefix when the profile still reads Nuevo Alumno.

topics

TopicMasteryView[]

Per-subdomain mastery rows, sorted by domain then subdomain code.

Show TopicMasteryView fields

topicCode

string

Subdomain code from the taxonomy.

topicName

string

Subdomain display name.

pKnown

number

Mean BKT pKnown across the topics under this subdomain. Falls back to attempt accuracy when no BKT record exists, and to the BKT prior (0.3) for untouched subdomains.

attemptsCount

number

Total attempts attributed to this subdomain.

attempts

AttemptHistoryView[]

Last 20 attempts in the course, ordered by most recent first.

Show AttemptHistoryView fields

string

Attempt UUID.

exercisePrompt

string

Exercise prompt text extracted from the exercise content JSON.

isCorrect

boolean

Whether the attempt was correct.

errorTagCode

string | null

Effective error tag code.

errorTagName

string | null

Error tag display name. null when not yet labeled.

classifierSource

string

RULE or LLM.

confidence

number | null

Classifier confidence.

createdAt

string

ISO 8601 timestamp.

errorFrequency

ErrorFrequencyView[]

Error tags ranked by frequency (incorrect attempts only).

Show ErrorFrequencyView fields

errorTagCode

string

Error tag code.

errorTagName

string | null

Error tag display name.

count

number

Number of occurrences.

percentage

number

Fraction of total errors (0–1).

Example

curl https://api.innova.app/mastery/course/crs_def456 \
  -H "Authorization: Bearer <token>"

GET /mastery/course/:courseId/heatmap

Student × Unit heatmap with topic drill-down (C12). The outer axis is Domain (unit); the inner drill-down is Subdomain (topic). pKnown per unit is the mean of its constituent subdomains. Only units and topics that have live signal in this course are returned — untouched cells are omitted rather than shown as a false 0. GET /mastery/course/:courseId/heatmap

Path parameters

courseId

string

required

UUID of the course.

Response `200`

courseId

string

The course UUID echoed back.

units

HeatmapUnit[]

Ordered list of live curriculum domains (units) for this course.

Show HeatmapUnit fields

string

Domain UUID.

code

string

Domain code (e.g. SUBTRACTION).

name

string

Domain display name.

sequence

number

1-based display order, sorted by domain code.

students

HeatmapStudent[]

One row per active enrollment.

Show HeatmapStudent fields

studentId

string

Student UUID.

displayName

string

Resolved display name.

units

UnitCell[]

Per-unit aggregated pKnown cells for this student. Only units with at least one live subdomain are included.

Show UnitCell fields

unitId

string

Domain UUID (matches units[].id).

pKnown

number

Mean pKnown across the unit’s live subdomains.

topicCount

number

Number of live subdomains contributing to this cell.

topics

TopicCell[]

Per-subdomain drill-down cells (only subdomains with signal for this student).

Show TopicCell fields

topicId

string

Subdomain UUID.

unitId

string

Parent domain UUID.

topicCode

string

Subdomain code.

topicName

string

Subdomain display name.

pKnown

number

BKT mastery for this subdomain.

Example

curl https://api.innova.app/mastery/course/crs_def456/heatmap \
  -H "Authorization: Bearer <token>"

Render pKnown values with a diverging colour scale: red at 0.0, yellow at 0.5 (the BKT prior is 0.3), green at 1.0. Values below 0.4 reliably indicate a struggling student for that unit.

GET /mastery/classroom/:classroomId

Alias for GET /mastery/course/:courseId — accepts a classroom ID in place of a course ID. The two identifiers are interchangeable; this route exists for legacy client compatibility. GET /mastery/classroom/:classroomId

Path parameters

classroomId

string

required

UUID of the classroom (course).

Response `200`

Identical shape to GET /mastery/course/:courseId. See that endpoint for full field documentation.

Example

curl https://api.innova.app/mastery/classroom/crs_def456 \
  -H "Authorization: Bearer <token>"

IRT Fisher-information next-exercise recommendation. Finds the student’s weakest topic (lowest pKnown), converts it to an ability estimate θ via the logit transform, then selects the exercise that maximises Fisher information I(θ) = a² · P(θ) · (1 − P(θ)). Exercises the student already answered correctly in the last 7 days are excluded. GET /mastery/recommend/:courseId/:studentId

Path parameters

courseId

string

required

UUID of the course to draw exercises from.

studentId

string

required

UUID of the student.

Response `200`

{
  "exercise": {
    "id": "ex_xyz789",
    "problem": "Calcula: 72 − 48",
    "topicCode": "T-SUB-BORROW",
    "topicName": "Resta con préstamo",
    "irtA": 1.2,
    "irtB": -0.3
  },
  "studentTheta": -0.74,
  "reasoning": "Tema: Resta con préstamo · p=0.32 · θ=-0.74 · Fisher=0.312"
}

exercise

object

The recommended exercise.

Show Exercise fields

string

Exercise UUID.

problem

string

Exercise prompt text.

topicCode

string

Curriculum topic code.

topicName

string

Topic display name.

irtA

number

IRT discrimination parameter a.

irtB

number

IRT difficulty parameter b (ability scale).

studentTheta

number

The student’s estimated ability θ on the logit scale, derived from pKnown via log(p / (1−p)).

reasoning

string

Human-readable explanation of why this exercise was chosen (useful for debugging).

Response `404`

Returned when the student has no mastery records yet, or all exercises for their weakest topic have already been answered correctly in the last 7 days.

{
  "statusCode": 404,
  "message": "No available exercises for this student"
}

Example

curl https://api.innova.app/mastery/recommend/crs_def456/stu_abc123 \
  -H "Authorization: Bearer <token>"

A 404 on this endpoint is not an error — it simply means the student has exhausted their current practice pool or has no mastery history yet. Present a fallback exercise or prompt the teacher to add more content for that topic.

Overview

Endpoints

Mastery API: BKT State and Heatmaps per Student

GET /mastery/:studentId

Path parameters

Response `200`

Example

GET /mastery/course/:courseId

Path parameters

Response `200`

Example

GET /mastery/course/:courseId/heatmap

Path parameters

Response `200`

Example

GET /mastery/classroom/:classroomId

Path parameters

Response `200`

Example

Path parameters

Response `200`

Response `404`

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /mastery/:studentId

​Path parameters

​Response 200

​Example

​GET /mastery/course/:courseId

​Path parameters

​Response 200

​Example

​GET /mastery/course/:courseId/heatmap

​Path parameters

​Response 200

​Example

​GET /mastery/classroom/:classroomId

​Path parameters

​Response 200

​Example

​GET /mastery/recommend/:courseId/:studentId

​Path parameters

​Response 200

​Response 404

​Example

Build docs developers (and LLMs) love

GET /mastery/:studentId

Path parameters

Response `200`

Example

GET /mastery/course/:courseId

Path parameters

Response `200`

Example

GET /mastery/course/:courseId/heatmap

Path parameters

Response `200`

Example

GET /mastery/classroom/:classroomId

Path parameters

Response `200`

Example

GET /mastery/recommend/:courseId/:studentId

Path parameters

Response `200`

Response `404`

Example