Skip to content

Timetable API Reference ​

GET /api/v1/timetable/imports ​

List import batches

Use to review the import history, newest first. Pass term_code to restrict the list to one term and limit to cap the number returned; the default is 100, values above 1000 are clamped and a non-positive or non-numeric limit answers 400 invalid_request. Each batch carries its status (dry_run, committed or failed), row counts and the per-row error list of the failed attempt.

Required permission — dispatch:read:any

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "created_at": "2026-08-21T10:30:00Z",
      "error_count": 0,
      "errors": [],
      "filename": "timetable-2026-fall.csv",
      "id": "01J8ZC1IMP2M4P6R8T0V2X4Z6B8",
      "imported_by": "01J8Z1USER3Y5W7A9C1E3G5J7L9",
      "mode": "replace",
      "ok_count": 3,
      "row_count": 3,
      "sha256": "9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
      "status": "committed",
      "term_code": "2026-FALL"
    }
  ]
}

Errors ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
500internal_errorInternal Server Error

POST /api/v1/timetable/imports ​

Import a timetable CSV

Use to upload one term's timetable as a multipart/form-data body whose single file part is named file (text/csv, at most 1 MiB and at most DISPATCH_MAX_IMPORT_ROWS data rows, default 5000). The header row is mandatory and matched by name in any order: term_code,course_code,course_name,teacher_username,room_code,weekday,period_start,period_end,weeks; unknown or missing columns reject the whole file. Every row must carry the same term_code, the term must exist, its 节次 table must cover period_start..period_end, room_code must be a bound enabled room and weeks must stay within the term's teaching weeks. Overlapping rows for the same room, weekday, period range and weeks are rejected; a teacher double-booking is not. A row whose occurrences collide with an existing live or planned recording on the same (device_id, camera_enum) is rejected with code session_collision, because one camera cannot record two sessions at once; in replace mode the batch's own term is excluded from that check, since the commit supersedes its pending sessions, while an append import still collides with them. Query parameters: mode=replace|append (default replace; replace supersedes the term's previous entries and cancels their future planned sessions, already started or completed sessions are never touched), dry_run=true (validate only, no entries or sessions are written) and force=true (commit even though the same sha256 was already committed for the term). A dry run answers 200 with the stored batch object plus a preview array ([{row,course_code,session_count,first_starts_at,last_ends_at}]) so a wrong week1_monday or period table is visible before anything is written; a commit answers 201 Created with the stored batch and a Location header; a blocking row error answers 422 with detail import_validation_failed and the full errors array ([{row,column,code,message}]) while writing the batch with status failed and nothing else; a teacher double-booking is a non-blocking warning that is stored in the batch errors array without rejecting the file, so a committed batch can carry warnings and error_count counts every reported entry; an identical already-committed file answers 409 duplicate_import unless force=true.

Required permission — dispatch:manage:any

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-08-21T10:30:00Z",
  "error_count": 0,
  "errors": [],
  "filename": "timetable-2026-fall.csv",
  "id": "01J8ZC1IMP2M4P6R8T0V2X4Z6B8",
  "imported_by": "01J8Z1USER3Y5W7A9C1E3G5J7L9",
  "mode": "replace",
  "ok_count": 3,
  "preview": [
    {
      "course_code": "CS101",
      "first_starts_at": "2026-09-07T08:00:00+08:00",
      "last_ends_at": "2026-12-21T09:40:00+08:00",
      "row": 2,
      "session_count": 16
    }
  ],
  "row_count": 3,
  "sha256": "9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
  "status": "dry_run",
  "term_code": "2026-FALL"
}

Errors ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
404term_not_foundNot Found
409duplicate_importConflict
422import_validation_failedUnprocessable Content; Unprocessable Content
422session_collisionUnprocessable Content; Unprocessable Content
500internal_errorInternal Server Error

GET /api/v1/timetable/imports/{id} ​

Get an import batch

Use to fetch one batch together with the per-row errors of a failed validation, so the operator can correct the CSV. An unknown batch id answers 404 invalid_request.

Required permission — dispatch:read:any

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "created_at": "2026-08-21T10:30:00Z",
  "error_count": 0,
  "errors": [],
  "filename": "timetable-2026-fall.csv",
  "id": "01J8ZC1IMP2M4P6R8T0V2X4Z6B8",
  "imported_by": "01J8Z1USER3Y5W7A9C1E3G5J7L9",
  "mode": "replace",
  "ok_count": 3,
  "row_count": 3,
  "sha256": "9f2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
  "status": "committed",
  "term_code": "2026-FALL"
}

Errors ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
500internal_errorInternal Server Error