Skip to content

api.md

Latest commit

 

History

History
114 lines (88 loc) · 3.38 KB

api.md

File metadata and controls

114 lines (88 loc) · 3.38 KB
Raw

API Reference

Base URL: /api/v1

All authenticated routes require Authorization: Bearer <token>.

Schools

Method Path Description
GET /schools List schools for login (public)

Authentication

Method Path Body Response
POST /auth/pupil-login { "school_id", "username", "pin" } { token, user }
POST /auth/staff-login { "school_id", "username", "password" } { token, refresh_token, user }
POST /auth/refresh { "refresh_token" } { token }
DELETE /auth/logout { "refresh_token" } 204
GET /auth/me — User

Session (pupil)

Method Path Description
GET /session/queue Today's adaptive queue (max 20)
POST /session/answer Submit answer event
GET /session/history Last 7 sessions

Answer payload

{
  "session_id": "uuid",
  "question_id": "uuid",
  "pupil_answer": { "type": "base10_blocks", "hundreds": 3, "tens": 4, "ones": 7 },
  "response_time_ms": 8450,
  "hints_used": 1
}

Answer response

{
  "is_correct": true,
  "partial_credit": 1.0,
  "ems_delta": 0.12,
  "new_ems": 0.63,
  "feedback": { "message": "...", "type": "success" },
  "next_question_id": "uuid"
}

Curriculum

Method Path Query params
GET /curriculum/modules year_group, strand
GET /curriculum/modules/:id —
GET /curriculum/questions/:id —

Questions return question_data (including ui_component) but not correct_answer_payload.

Progress (pupil)

Method Path Description
GET /progress/skills Own EMS per sub-skill + mastery level
GET /progress/badges Earned star badges

Teacher

Method Path Description
GET /teacher/class Class EMS overview (?class_name=)
GET /teacher/pupil/:id Individual skill matrix
GET /teacher/alerts Persistent struggle alerts
POST /teacher/assign Regenerate queue / assign topic

Admin

Method Path Description
GET /admin/classrooms List classrooms (with pupil counts)
POST /admin/classrooms Create classroom
PATCH /admin/classrooms/:id Update classroom / assign teacher
DELETE /admin/classrooms/:id Delete empty classroom
GET /admin/users?role=pupil|teacher|staff List users
POST /admin/users Create user
PATCH /admin/users/:id Update user / reset PIN or password
POST /admin/users/bulk Bulk user import (JSON array)
DELETE /admin/users/:id GDPR erasure
GET /assessments List available assessments
POST /assessments/:id/start Pupil starts fixed assessment queue
GET /teacher/school Headteacher school-wide EMS overview
GET/POST /teacher/intervention-groups Intervention group management
PATCH /senco/pupil/:id/send-flags SENCO accommodation flags
POST /admin/users/bulk-csv CSV user import (multipart file)

Operations

Method Path Description
GET /healthz Liveness
GET /readyz Readiness (includes DB ping)
GET /metrics Prometheus metrics

Roles

pupil · teacher · senco · headteacher · it_admin

Teacher routes allow teacher, senco, headteacher. Admin routes allow it_admin, headteacher.