List Timetables

Retrieve every timetable version belonging to your organisation, newest first.

Endpoint

GET /api/v1/timetables

ERP partners list timetables at GET /api/partner/v1/timetables. See Reading schedules.

Authentication

Authorization: Bearer ttm_YOUR_API_KEY

See Authentication.

Parameters

None.

Response

{
  "success": true,
  "data": {
    "orgId": "6913a0c4e1b2f3a4b5c6d7e8",
    "count": 2,
    "timetables": [
      {
        "id": "6a34108b1d16898202940188",
        "name": "Term 1 2026",
        "groupId": "6a3410551d16898202940101",
        "versionNumber": 3,
        "versionName": null,
        "status": "published",
        "isCurrent": true,
        "publishedAt": "2026-08-28T07:15:00.000Z",
        "effectiveFrom": 20260901,
        "effectiveTo": null,
        "schedulingMode": "standard",
        "createdAt": "2026-07-01T09:12:00.000Z",
        "updatedAt": "2026-08-28T07:15:00.000Z"
      },
      {
        "id": "6a33f0021d16898202940150",
        "name": "Term 1 2026",
        "groupId": "6a3410551d16898202940101",
        "versionNumber": 2,
        "versionName": "Before the new science lab",
        "status": "draft",
        "isCurrent": false,
        "publishedAt": null,
        "effectiveFrom": null,
        "effectiveTo": null,
        "schedulingMode": "standard",
        "createdAt": "2026-06-20T11:02:00.000Z",
        "updatedAt": "2026-06-30T15:40:00.000Z"
      }
    ]
  },
  "timestamp": "2026-10-06T10:00:00.000Z"
}

Each entry is one version. A timetable usually has several, and they share a groupId and a name. Autosaves are not listed.

Field	Type	Notes
id	string	This version. Pass it to Get Timetable
name	string	The timetable's name, shared by all its versions. Untitled when none was given
groupId	string	Shared by every version of the same timetable
versionNumber	number	Increases with each new version
versionName	string	A label given to the version, or null
status	string	draft or published. Only show published timetables to staff and students
isCurrent	boolean	true for the version currently in use
publishedAt	string	When it was published, null for a draft
effectiveFrom, effectiveTo	number	The dates a published version applies, as YYYYMMDD. effectiveTo: null means open-ended
schedulingMode	string	standard (class-based) or student-level

To find the timetable in use today, pick the entry with status: "published" whose effectiveFrom/effectiveTo window covers today's date.

Example

curl -H "Authorization: Bearer ttm_YOUR_API_KEY" \
  https://api.timetablemaster.com/api/v1/timetables

Errors

Status	Code	Meaning
401	INVALID_API_KEY	Missing, invalid, expired or revoked key, or API access is not enabled for your organisation
402	ACCESS_EXPIRED, ACCOUNT_SUSPENDED	Your organisation's access has ended or is suspended
500	INTERNAL_ERROR	Unexpected server error

See Authentication errors for the response bodies.