Assignments and Practice: IRT-Powered Recommendations

The Assignments and Practice APIs let teachers create exercise sets for students — either manually curated or automatically selected using IRT (Item Response Theory) Fisher information maximization. The assignments module handles persisted, multi-exercise assignments that appear in the student’s task list; the practice module complements it with a real-time recommender that always surfaces the single most informative exercise for a given student.

POST /assignments

Create a new assignment for a whole course or a specific subset of students. The teacher specifies exercise IDs, an optional due date, and a reason code that signals whether the assignment was manually curated or generated by the recommender. Auth: JWT (bearer token required; caller must be a teacher)

Request body

title

string

required

Human-readable assignment title displayed to students.

exerciseIds

string[]

required

Ordered list of exercise UUIDs to include. The array order determines the display sequence.

reason

string

required

Describes how the assignment was created. Must be one of the AssignmentReason enum values:

Value	Description
`TEACHER_MANUAL`	Teacher selected exercises by hand.
`PRACTICE_RECOMMENDER`	Exercises were selected by the IRT Fisher-information recommender.

courseId

string

UUID of the course. When provided, the assignment targets all enrolled students in the course.

studentIds

string[]

Array of student UUIDs. Use this instead of (or alongside) courseId to target a specific subset of students.

dueAt

string

ISO 8601 date-time string for the due date (e.g. "2024-11-30T23:59:00.000Z"). Omit for open-ended assignments.

Response

Returns the full Assignment Prisma record, including the nested assignmentExercises (with exercise details) and targets (per-student status records).

string

UUID of the created assignment.

title

string

Assignment title.

reason

string

The AssignmentReason value that was stored.

dueAt

string | null

ISO 8601 due date, or null.

assignmentExercises

array

Ordered exercise entries, each containing the full exercise record.

targets

array

One entry per targeted student with an initial status of PENDING.

Example request

curl -X POST https://api.example.com/assignments \
  -H "Authorization: Bearer <teacher_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Álgebra — Semana 3",
    "exerciseIds": ["ex_aaa111", "ex_bbb222", "ex_ccc333"],
    "reason": "TEACHER_MANUAL",
    "studentIds": ["stu_001", "stu_002"],
    "dueAt": "2024-10-15T23:59:00.000Z"
  }'

Create an IRT-recommended assignment for a specific student. The server computes the IRT 2-PL Fisher information for every active exercise against the student’s current BKT mastery estimates, selects the top-5 highest-information exercises (optionally scoped to a topic), and persists them as an assignment. Auth: JWT (bearer token required; caller must be a teacher)

Query parameters

studentId

string

required

UUID of the student for whom exercises should be recommended.

topicId

string

Curriculum topic UUID. When provided, only exercises belonging to that topic are considered.

Response

Same shape as POST /assignments. The title is auto-generated (e.g. "Práctica recomendada — ALG-2") and reason is always PRACTICE_RECOMMENDER.

Example request

curl -X POST "https://api.example.com/assignments/recommend?studentId=stu_001&topicId=topic_alg2" \
  -H "Authorization: Bearer <teacher_jwt>"

Recommendations respect prerequisite gating. If a topic has prerequisites whose pKnown is below 0.6, that topic’s exercises are excluded from the candidate pool regardless of Fisher information score.

GET /assignments/student/:id

List all assignments targeted at a student. Includes the full exercise list (with topic metadata) for each assignment, ordered newest first. This endpoint is intentionally broad — it can be called by the student themselves, a teacher, or a parent view. Auth: JWT

Path parameters

string

required

UUID of the student whose assignments to retrieve.

Response

Returns an array of AssignmentTarget records, each joined with the parent Assignment and its ordered exercises.

[].assignment.id

string

Assignment UUID.

[].assignment.title

string

Assignment title.

[].assignment.dueAt

string | null

Due date if set.

[].status

string

Per-student status: PENDING, IN_PROGRESS, or COMPLETED.

[].assignment.assignmentExercises

array

Ordered exercises with full topic information.

Example request

curl https://api.example.com/assignments/student/stu_001 \
  -H "Authorization: Bearer <jwt>"

POST /practice/assign

Create an adaptive practice assignment for a single student. This is a convenience wrapper around POST /assignments that uses the TEACHER_MANUAL reason and accepts itemIds (synonymous with exerciseIds). Auth: JWT (bearer token required; caller must be a teacher)

Request body

studentId

string

required

UUID of the student to assign practice to.

itemIds

string[]

required

Array of exercise UUIDs to include in the practice assignment.

dueAt

string

Optional ISO 8601 due date string.

Response

string

UUID of the created assignment.

studentId

string

UUID of the assigned student (echoed from request body).

itemIds

string[]

The exercise IDs that were assigned (echoed from request body).

dueAt

string

ISO 8601 due date, if one was provided.

Example request

curl -X POST https://api.example.com/practice/assign \
  -H "Authorization: Bearer <teacher_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "studentId": "stu_001",
    "itemIds": ["ex_aaa111", "ex_bbb222"],
    "dueAt": "2024-10-20T23:59:00.000Z"
  }'

Return the single exercise from the active pool that maximises IRT 2-PL Fisher information for the student’s current ability estimate. This endpoint does not persist anything — it is designed for “next card” display in a live practice session. Auth: JWT Algorithm:

Load the student’s BKT mastery estimates (pKnown) per topic.
Convert each pKnown to a logit ability estimate θ (clamped to the range [0.05, 0.95]).
For every active exercise, compute I(θ) = a² · P(θ) · (1 − P(θ)) where a is the IRT discrimination parameter and b is the difficulty parameter.
Return the exercise with the highest I(θ).

If the student has no mastery record for a topic, pKnown = 0.3 (θ ≈ −0.85) is assumed, which steers toward slightly-below-average difficulty items.

Query parameters

studentId

string

required

UUID of the student for whom to recommend the next exercise.

domainId

string

Curriculum domain UUID. When provided, only exercises whose topic belongs to this domain are considered (capped at 500 records).

Response

exercise

object

The recommended exercise.

Show exercise fields

string

Exercise UUID.

problem

string

Exercise prompt text extracted from the content.prompt JSON field.

topicCode

string

Curriculum topic code (e.g. "ALG-2").

topicName

string

Human-readable topic name.

irtA

number

IRT 2-PL discrimination parameter (a).

irtB

number

IRT 2-PL difficulty parameter (b).

studentTheta

number

The logit ability estimate θ that was used for scoring. Useful for debugging adaptive behaviour.

reasoning

string

Human-readable explanation, e.g. "θ = -0.85, b = -0.90 → I(θ) = 0.421 (Fisher máx)".

Example request

curl "https://api.example.com/practice/recommend-next?studentId=stu_001&domainId=dom_algebra" \
  -H "Authorization: Bearer <jwt>"

Example response

{
  "exercise": {
    "id": "ex_bbb222",
    "problem": "Resuelve para x: 3x − 7 = 2",
    "topicCode": "ALG-2",
    "topicName": "Ecuaciones lineales",
    "irtA": 1.4,
    "irtB": -0.9
  },
  "studentTheta": -0.85,
  "reasoning": "θ = -0.85, b = -0.90 → I(θ) = 0.493 (Fisher máx)"
}

POST /assignments/recommend and GET /practice/recommend-next both use Fisher information to select exercises, but they serve different purposes:

/assignments/recommend — Creates a persisted Assignment record for a student (top-5 exercises). The student sees it in their task list with a due date.
/practice/recommend-next — Returns a single exercise object for immediate display. Nothing is saved. Ideal for a “next question” button in a live adaptive practice UI.

Overview

Endpoints

Assignments and Practice: IRT-Powered Recommendations

POST /assignments

Request body

Response

Query parameters

Response

GET /assignments/student/:id

Path parameters

Response

POST /practice/assign

Request body

Response

Query parameters

Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /assignments

​Request body

​Response

​POST /assignments/recommend

​Query parameters

​Response

​GET /assignments/student/:id

​Path parameters

​Response

​POST /practice/assign

​Request body

​Response

​GET /practice/recommend-next

​Query parameters

​Response

​Recommend vs. assign

Build docs developers (and LLMs) love

POST /assignments

Request body

Response

POST /assignments/recommend

Query parameters

Response

GET /assignments/student/:id

Path parameters

Response

POST /practice/assign

Request body

Response

GET /practice/recommend-next

Query parameters

Response

Recommend vs. assign