Skills and Items API: Curriculum Catalog and Exercise Bank

The Skills and Items APIs expose the curriculum taxonomy and exercise bank. Use these endpoints to browse topics, search error codes, and manage or generate exercises. Skills (backed by the Topic model) represent curriculum units such as “Subtraction with Borrowing,” while Items (backed by Exercise) are the individual problems students attempt, each carrying IRT calibration parameters.

Skills

GET /skills

List all skills (topics) in the curriculum, ordered by unit. Authentication: JWT required

curl -X GET https://api.example.com/skills \
  -H "Authorization: Bearer <token>"

string

UUID of the topic.

code

string

Short key (e.g. subtraction_borrow).

name

string

Human-readable display name.

unitId

string

UUID of the parent unit.

description

string

Optional description of the topic.

GET /skills/taxonomy

Return the full math error taxonomy as a tree: domains → subdomains. This is the classification catalog used by the guide wizard and the AI classifier engine. Unlike the curriculum topics, the taxonomy is always fully populated. Authentication: JWT required

curl -X GET https://api.example.com/skills/taxonomy \
  -H "Authorization: Bearer <token>"

string

Domain UUID.

code

string

Short domain code (e.g. ARITH, FRACT, GEOM).

name

string

Domain display name.

subdomains

array

Array of { id, code, name } objects — the subdomains belonging to this domain.

GET /skills/error-tags

Search the ACTIVE error catalog. Used by the teacher manual-override UI to populate the typeahead when a teacher wants to override an automatically assigned error tag. Reads the live backend catalog (2,600+ tags) rather than any bundled seed, so results always match what the classifier can assign. Authentication: JWT required

string

Case-insensitive substring search over code, name, and description.

domainCode

string

Filter to a single domain (e.g. ARITH, FRACT). Pick codes from GET /skills/taxonomy.

limit

number

Maximum results to return. Clamped to [1, 50]. Defaults to 20.

curl "https://api.example.com/skills/error-tags?q=borrow&domainCode=ARITH&limit=10" \
  -H "Authorization: Bearer <token>"

code

string

Error tag code (e.g. ARITH_SUB_BORROW_OMITTED_TENS_G3).

name

string

Human-readable error name.

subdomainCode

string | null

Subdomain this tag belongs to, if set.

domainCode

string | null

Parent domain code.

This endpoint is intentionally separate from GET /admin/error-tags. It is scoped to ACTIVE tags only and supports fast typeahead queries (max 50 results). Admins who need to page through the full catalog — including DRAFT or DEPRECATED tags — should use the admin endpoint instead.

GET /skills/:id

Get a single skill by UUID. Authentication: JWT required

string

required

UUID of the skill (topic).

POST /skills

Create a new skill (topic). The service automatically associates the new topic with the first available unit. If no units exist, run pnpm seed:full first. Authentication: JWT required

key

string

required

Short code used throughout the system (e.g. subtraction_borrow). Maps to the code column.

name

string

required

Display name (e.g. Subtraction with Borrowing).

description

string

Optional description of the topic.

curl -X POST https://api.example.com/skills \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "subtraction_borrow",
    "name": "Subtraction with Borrowing",
    "description": "Multi-digit subtraction requiring regrouping across columns"
  }'

Response: 201 Created — the created Topic object.

PATCH /skills/:id

Update an existing skill. All fields from CreateSkillDto are optional. Authentication: JWT required

string

required

UUID of the skill to update.

key

string

New short code. Updates the code column.

name

string

New display name.

description

string

New description.

DELETE /skills/:id

Delete a skill by UUID. Authentication: JWT required

string

required

UUID of the skill to delete.

Response: 204 No Content on success. Returns false (not 404) if the skill does not exist — check your UUID.

GET /skills/:id/prerequisites

Traverse the prerequisite graph for a skill. Returns the list of prerequisite topic codes that must be mastered before this skill. Authentication: JWT required

string

required

UUID of the skill.

curl https://api.example.com/skills/f3a1b2c4-d5e6-7890-abcd-ef1234567890/prerequisites \
  -H "Authorization: Bearer <token>"

skillId

string

The requested skill UUID.

prerequisites

array

Array of prerequisite topic code strings.

Items

GET /items

List exercise bank items, optionally filtered by skill/topic code. Only ACTIVE exercises are returned. Authentication: JWT required

skillKey

string

Filter by topic code (e.g. subtraction_borrow). The topic query param is accepted as an alias.

topic

string

Alias for skillKey.

limit

number

Number of items to return. Defaults to 32. Clamped to [1, 100].

curl "https://api.example.com/items?skillKey=subtraction_borrow&limit=10" \
  -H "Authorization: Bearer <token>"

string

UUID of the exercise.

topicId

string

UUID of the associated topic.

topicCode

string

Short topic code.

topicName

string

Topic display name.

content

object

{ prompt, problem, expectedAnswer, correct_answer_latex } — the exercise content.

difficulty

string

Derived from irtB: easy (≤ −0.4), medium, or hard (≥ 0.7).

irtA

number

IRT discrimination parameter.

irtB

number

IRT difficulty parameter.

source

string

Origin of the exercise (e.g. TEACHER_AUTHORED, AI_GENERATED).

createdAt

string

ISO 8601 timestamp.

POST /items

Create a new exercise item. The skillId field is resolved as a topic UUID for backward compatibility. Authentication: JWT required

skillId

string

required

UUID of the topic (skill) this exercise belongs to.

content

object

required

Exercise content object. Must contain prompt (string, non-empty). Example: { "prompt": "53 - 26" }.

irtA

number

required

IRT discrimination parameter (e.g. 1.1).

irtB

number

required

IRT difficulty parameter (e.g. -0.25).

curl -X POST https://api.example.com/items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "skillId": "f3a1b2c4-d5e6-7890-abcd-ef1234567890",
    "content": { "prompt": "53 - 26" },
    "irtA": 1.1,
    "irtB": -0.25
  }'

Response: 201 Created — the raw Exercise database record.

The source field is automatically set to TEACHER_AUTHORED for items created via this endpoint.

GET /items/:id

Get a single exercise item by UUID. Authentication: JWT required

string

required

UUID of the exercise item.

Response: An ItemView object (same shape as the array items returned by GET /items). Returns 404 if the exercise does not exist.

GET /items/:id/irt

Get read-only IRT (Item Response Theory) parameters for an exercise. Use this to inspect calibration data without loading the full item content. Authentication: JWT required

string

required

UUID of the exercise item.

curl https://api.example.com/items/abc123/irt \
  -H "Authorization: Bearer <token>"

irtA

number

Discrimination parameter — how well the item differentiates ability levels. Higher values indicate steeper item characteristic curves.

irtB

number

Difficulty parameter — the ability level at which a student has a 50% probability of answering correctly. Negative values indicate easier items.

The IRT parameters stored here are the values set at item creation or last update. Continuous calibration from student response data is handled by the AI engine pipeline — check the classifiedAt field on Attempt records for calibration timestamps.

POST /items/generate

Enqueue an AI exercise generation job for a subdomain. The request is published to the EXERCISE_GENERATE_QUEUE_URL SQS queue and returns immediately with 202 Accepted. Generated items will appear in the bank within a few minutes, depending on queue depth. Authentication: JWT required

subdomainCode

string

required

Subdomain code to generate exercises for (e.g. subtraction_borrow).

gradeLevel

number

required

Target grade level (1–12).

targetErrorCodes

array

required

Array of error tag codes the generated items should target (e.g. ["ARITH_SUB_BORROW_OMITTED_TENS_G3"]).

count

number

required

Number of exercises to generate (1–10).

curl -X POST https://api.example.com/items/generate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomainCode": "subtraction_borrow",
    "gradeLevel": 4,
    "targetErrorCodes": ["ARITH_SUB_BORROW_OMITTED_TENS_G3", "ARITH_SUB_BORROW_NO_DECREMENT_G3"],
    "count": 5
  }'

Response: 202 Accepted

{
  "generated": 0,
  "message": "Generación de 5 ejercicio(s) encolada. Aparecerán en el banco en unos minutos."
}

generated

number

Always 0 at enqueue time — the items have not been created yet.

message

string

Confirmation message (in Spanish, matching the Chilean curriculum context).

This endpoint triggers real AI inference. Generating large batches (count close to 10) on short subdomains with many targetErrorCodes can take several minutes and incur LLM cost. Monitor the cost section of GET /admin/status after enqueuing large jobs.

Overview

Endpoints

Skills and Items API: Curriculum Catalog and Exercise Bank

Skills

GET /skills

GET /skills/taxonomy

GET /skills/error-tags

GET /skills/:id

POST /skills

PATCH /skills/:id

DELETE /skills/:id

GET /skills/:id/prerequisites

Items

GET /items

POST /items

GET /items/:id

GET /items/:id/irt

POST /items/generate

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Skills

​GET /skills

​GET /skills/taxonomy

​GET /skills/error-tags

​GET /skills/:id

​POST /skills

​PATCH /skills/:id

​DELETE /skills/:id

​GET /skills/:id/prerequisites

​Items

​GET /items

​POST /items

​GET /items/:id

​GET /items/:id/irt

​POST /items/generate

Build docs developers (and LLMs) love

Skills

GET /skills

GET /skills/taxonomy

GET /skills/error-tags

GET /skills/:id

POST /skills

PATCH /skills/:id

DELETE /skills/:id

GET /skills/:id/prerequisites

Items

GET /items

POST /items

GET /items/:id

GET /items/:id/irt

POST /items/generate