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

Shared methods (Parent & Student)

All methods require await client.login() first. Session auto-renews after 3 minutes.

Parent-only methods

Student-only methods

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\x3CData, 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.

Links

• Library docs
• Unofficial API docs
• GitHub