Skip to main content

Reading schedules

Pull the generated timetable back into your product.

GET /api/partner/v1/timetables
GET /api/partner/v1/timetables/{id}

How a timetable is put together​

Three pieces fit together:

  • Bell schedule: the days and periods. A placement is a (dayId, periodIndex) pair.
  • Entities: teachers, subjects, rooms, classes. Each has a localId (this timetable) and your externalId.
  • Lesson units: one per scheduled period, referencing entities by localId.

One request returns the whole timetable, so filtering is yours to do locally. To render "what is Edna teaching on Monday period 3", find her localId in teachers by her externalId, then take the units whose teacherIds contain it, with dayId Monday and periodIndex 2.

Full timetable​

GET /api/partner/v1/timetables/{id}
{
  "id": "6913…",
  "name": "Term 1",
  "status": "published",
  "schedulingMode": "standard",
  "bellSchedule": {
    "scheduleType": "weekly",
    "cycleLength": 1,
    "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" } ],
        "breaks":  [ { "id": "b1", "name": "Break", "startTime": "10:30", "endTime": "10:45", "followsPeriodIndex": 1 } ] }
    ]
  },
  "teachers": [ { "localId": "tch_…", "externalId": "EMP-1001", "name": "Edna Krabappel", "shortName": "EK", "color": "#3B82F6", "isActive": true } ],
  "subjects": [ ], "rooms": [ ], "classes": [ ],
  "lessonUnits": [
    {
      "localId": "lu_…",
      "lessonLocalId": "lsn_…",
      "dayId": "day_w_0_d_0",
      "periodIndex": 0,
      "spanId": null,
      "parallelGroupId": null,
      "groupName": null,
      "locked": false,
      "teacherIds": ["tch_…"],
      "classIds":   ["cls_…"],
      "subjectIds": ["sub_…"],
      "roomIds":    ["rom_…"],
      "studentIds": []
    }
  ]
}

status is draft or published. Only published timetables are safe to surface to staff and students; a draft is still being worked on.

Reading lesson units​

  • Unscheduled units have dayId: null and periodIndex: null. The system could not place them. Skip them when rendering a grid.
  • Multi-period lessons are several units sharing a spanId. A double period is two units, so the duration is the number of units with that spanId. (There is no length field.)
  • Parallel lessons (options blocks, split groups) share a parallelGroupId and occupy the same slot. groupName names the individual group, parallelGroupName the whole block.
  • Room groups: when roomGroupName is set and roomIds is empty, any room in that group is acceptable.

Not yet available: date resolution​

These endpoints return the timetable's repeating pattern, placements as (dayId, periodIndex), not a resolved calendar. Mapping "14 September 2026" to a specific dayId is your side's job today, and for a simple weekly schedule it is a straightforward weekday lookup.

For organisations on day-rotation schedules (A/B days, multi-week cycles), the mapping advances by teaching days and skips holidays, so it cannot be derived from the calendar alone. A date-resolved endpoint is planned. If you need it, tell us. It affects the priority.