Get Timetable

Retrieve one timetable in full: its bell schedule, entities, and every lesson unit.

Endpoint

GET /api/v1/timetables/{id}

Also available at GET /api/partner/v1/timetables/{id} for ERP partners. Both paths return the same payload.

Authentication

Authorization: Bearer ttm_YOUR_API_KEY

Path parameters

Parameter	Type	Description
id	string	Timetable id, from List Timetables

How the response fits together

• Bell schedule defines days and periods. A placement is a (dayId, periodIndex) pair.
• Entities (teachers, subjects, rooms, classes) each carry a localId (an identifier scoped to this timetable) plus externalId, your own identifier, when one has been synced.
• Lesson units are one per scheduled period and reference entities by localId.

To render a grid, walk lessonUnits, place each at its (dayId, periodIndex), and resolve its teacherIds / classIds / subjectIds / roomIds against the entity lists.

Response

{
  "success": true,
  "data": {
    "id": "6a34108b1d16898202940188",
    "name": "Term 1 2026",
    "status": "published",
    "schedulingMode": "standard",
    "versionNumber": 3,
    "effectiveFrom": 20260901,
    "effectiveTo": null,

    "bellSchedule": {
      "scheduleType": "weekly",
      "cycleLength": 1,
      "name": "Standard",
      "days": [
        { "id": "day_w_0_d_0", "label": "Monday", "shortLabel": "Mon", "dayOfWeek": 1, "weekInCycle": 0 }
      ],
      "dayConfigurations": [
        {
          "id": "dc1",
          "dayIds": ["day_w_0_d_0"],
          "periods": [
            { "id": "p1", "name": "P1", "startTime": "09:00", "endTime": "09:45" },
            { "id": "p2", "name": "P2", "startTime": "09:45", "endTime": "10:30" }
          ],
          "breaks": [
            { "id": "b1", "name": "Break", "startTime": "10:30", "endTime": "10:45", "followsPeriodIndex": 1 }
          ]
        }
      ]
    },

    "teachers": [
      { "localId": "tch_68d0…", "externalId": "EMP-1001", "name": "Edna Krabappel",
        "shortName": "EK", "color": "#3B82F6", "isActive": true }
    ],
    "subjects": [ ],
    "rooms": [ ],
    "classes": [ ],

    "lessons": [
      { "localId": "lsn_cecf…", "groups": [ ] }
    ],

    "lessonUnits": [
      {
        "localId": "lu_0001…",
        "lessonLocalId": "lsn_cecf…",
        "sectionLocalId": null,
        "dayId": "day_w_0_d_0",
        "periodIndex": 0,
        "spanId": null,
        "parallelGroupId": null,
        "groupName": null,
        "parallelGroupName": null,
        "distributionGroupId": null,
        "roomGroupName": null,
        "locked": false,
        "lockReason": null,
        "teacherIds": ["tch_68d0…"],
        "classIds":   ["cls_6911…"],
        "subjectIds": ["sub_6923…"],
        "roomIds":    [],
        "studentIds": []
      }
    ]
  },
  "timestamp": "2026-09-14T10:00:00.000Z"
}

Entity fields

Field	Notes
localId	Identity within this timetable. Lesson units reference this
externalId	Your identifier, when the entity was synced. null otherwise
isActive	false for an entity removed from the organisation but still used by this timetable

Lesson unit fields

Field	Notes
dayId, periodIndex	Placement. Both null when the unit could not be scheduled
spanId	Multi-period lessons are several units sharing this id. Duration = how many share it
parallelGroupId	Units in the same slot (options blocks, split groups)
groupName	Name of one group within a parallel block
roomGroupName	When set and roomIds is empty, any room in that group works
locked	The unit was placed by hand and is pinned
*Ids	References to entities by localId

There is no length field: a double period is two units sharing a spanId.

Student-level timetables

When schedulingMode is student-level, the response also includes students and sections.

Example

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

Errors

Status	Code	Meaning
401	INVALID_API_KEY	Missing, invalid, expired or revoked key
404	TIMETABLE_NOT_FOUND	No such timetable, or it belongs to another organisation
500	INTERNAL_ERROR	Unexpected server error

See also

• Reading schedules: per-entity schedules