Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 500 | internal_error | Internal 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
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | term_not_found | Not Found |
| 409 | duplicate_import | Conflict |
| 422 | import_validation_failed | Unprocessable Content; Unprocessable Content |
| 422 | session_collision | Unprocessable Content; Unprocessable Content |
| 500 | internal_error | Internal 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
| Parameter | Description |
|---|---|
| id | Path 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
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 500 | internal_error | Internal Server Error |