m0nkmaster ClassCharts API (JavaScript/TypeScript)
ClassCharts is a UK education classroom management platform. This skill uses the unofficial classcharts-api JS library to fetch homework, behaviour, timetable, detentions, attendance, announcements, badges, and more. Supports both Parent and Student authentication.
Important: The API is unofficial. Never hardcode credentials in prompts, logs, or committed code. Use environment variables or a secure secret store.
Installation
npm install classcharts-api
Requirements: Node.js 20+ or Deno
Authentication
Two client types with different login flows:
Parent Client
Parent logs in with email and password. Access to all linked pupils.
import { ParentClient } from "classcharts-api";
const client = new ParentClient(
process.env.CLASSCHARTS_EMAIL!,
process.env.CLASSCHARTS_PASSWORD!,
);
await client.login();
// Defaults to first pupil; switch with selectPupil
const pupils = client.pupils; // or await client.getPupils()
client.selectPupil(pupils[1].id); // if multiple children
Student Client
Student logs in with ClassCharts code and date of birth.
import { StudentClient } from "classcharts-api";
// Date of birth MUST be DD/MM/YYYY
const client = new StudentClient(
process.env.CLASSCHARTS_CODE!, // e.g. "ABCD1234"
"01/01/2010",
);
await client.login();
Date formats
| Use case | Format | Example |
|---|---|---|
| API options (from, to, date) | YYYY-MM-DD |
"2024-03-10" |
| Student date of birth (login) | DD/MM/YYYY |
"01/01/2010" |
| getStudentCode dateOfBirth | YYYY-MM-DD |
"2010-01-01" |
Shared methods (Parent & Student)
All methods require await client.login() first. Session auto-renews after 3 minutes.
| Method | Options | Description |
|---|---|---|
getStudentInfo() |
— | Student profile and metadata |
getActivity({ from, to, last_id? }) |
Dates YYYY-MM-DD, optional pagination |
Activity feed (paginated) |
getFullActivity({ from, to }) |
Dates YYYY-MM-DD |
Activity between dates (auto-paginates) |
getBehaviour({ from?, to? }) |
Dates YYYY-MM-DD |
Behaviour points timeline and reasons |
getHomeworks({ from?, to?, displayDate? }) |
Dates, displayDate: "due_date" | "issue_date" |
Homework list |
getLessons({ date }) |
date: YYYY-MM-DD |
Timetable for a specific date |
getBadges() |
— | Earned badges |
getAnnouncements() |
— | School announcements |
getDetentions() |
— | Detentions |
getAttendance({ from, to }) |
Dates YYYY-MM-DD |
Attendance records |
getPupilFields() |
— | Custom pupil fields/stats |
Parent-only methods
| Method | Description |
|---|---|
getPupils() |
List pupils linked to parent account |
selectPupil(pupilId) |
Set active pupil for subsequent requests |
changePassword(current, new) |
Change parent account password |
Student-only methods
| Method | Description |
|---|---|
getRewards() |
Rewards shop items and balance |
purchaseReward(itemId) |
Purchase item from rewards shop |
getStudentCode({ dateOfBirth }) |
Get student code (dateOfBirth: YYYY-MM-DD) |
Quick examples
// Homework for date range
const homeworks = await client.getHomeworks({
from: "2024-03-01",
to: "2024-03-31",
displayDate: "due_date",
});
// Today's timetable
const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
const lessons = await client.getLessons({ date: today });
// Behaviour summary
const behaviour = await client.getBehaviour({
from: "2024-01-01",
to: "2024-03-10",
});
// Student: list rewards shop and purchase
const rewards = await client.getRewards();
const purchase = await client.purchaseReward(rewards.data[0].id);
Response shape
Responses follow ClassChartsResponse<Data, Meta>:
{
success: 1,
data: T, // Array or object depending on endpoint
meta: M, // Session ID, dates, counts, etc.
error?: string
}
Errors throw if success === 0.
When to use this skill
- User asks about ClassCharts, school homework, behaviour points, timetable, detentions, attendance, or rewards.
- User wants to script, integrate, or automate ClassCharts data.
- User mentions parent/student portal in the context of UK schools and ClassCharts.