Appearance
Terms API Reference
GET /api/v1/terms
List terms
Use to enumerate the teaching terms. Pass 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. Terms are not filtered by scope: collection routes require the any-scoped key: rows are returned unfiltered, so no narrower scope can grant access.
Required permission — dispatch:read:any
Responses
- 200 — Successful response
json
{
"items": [
{
"created_at": "2026-08-20T09:00:00Z",
"name": "2026 秋季学期",
"term_code": "2026-FALL",
"updated_at": "2026-08-20T09:00:00Z",
"week1_monday": "2026-09-07T00:00:00Z",
"weeks": 16
}
]
}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/terms
Create or replace a term
Use to create a term or replace its fields. term_code identifies the term, week1_monday is the Monday of teaching week 1 as YYYY-MM-DD and weeks counts teaching weeks (1-30). Posting an existing term_code replaces name, week1_monday and weeks, which keeps a corrected re-import deterministic. The request answers 201 Created with the stored term.
Required permission — dispatch:manage:any
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| name | string | Yes |
| term_code | string | Yes |
| week1_monday | string | Yes |
| weeks | integer | Yes |
json
{
"name": "2026 秋季学期",
"term_code": "2026-FALL",
"week1_monday": "2026-09-07",
"weeks": 16
}Responses
- 200 — Successful response
json
{
"created_at": "2026-08-20T09:00:00Z",
"name": "2026 秋季学期",
"term_code": "2026-FALL",
"updated_at": "2026-08-20T09:00:00Z",
"week1_monday": "2026-09-07T00:00:00Z",
"weeks": 16
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 409 | invalid_request | Conflict |
| 500 | internal_error | Internal Server Error |
GET /api/v1/terms/{term_code}/periods
Get a term's period table
Use to fetch the term's 节次 table. Periods define the wall-clock window of every period_no; imports validate rows against them. A term without a configured table answers 404 periods_not_configured instead of an empty list.
Required permission — dispatch:read:any
Path parameters
| Parameter | Description |
|---|---|
| term_code | Path parameter. |
Responses
- 200 — Successful response
json
{
"items": [
{
"end_time": "08:45",
"period_no": 1,
"start_time": "08:00"
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | periods_not_configured | Not Found; Not Found |
| 404 | term_not_found | Not Found; Not Found |
| 500 | internal_error | Internal Server Error |
PUT /api/v1/terms/{term_code}/periods
Replace a term's period table
Use to replace the term's whole 节次 table in one call. The body is {"periods":[{"period_no":N,"start_time":"HH:MM","end_time":"HH:MM"}]}; period_no must be 1-20 and unique, both times are HH:MM local time and end_time must be after start_time. The period numbers of existing sessions are not re-validated, so re-import a term's timetable after changing its table. The response is 200 with the replaced table.
Required permission — dispatch:manage:any
Path parameters
| Parameter | Description |
|---|---|
| term_code | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| periods | array<object> | Yes |
json
{
"periods": [
{
"end_time": "08:45",
"period_no": 1,
"start_time": "08:00"
},
{
"end_time": "09:40",
"period_no": 2,
"start_time": "08:55"
}
]
}Responses
- 200 — Successful response
json
{
"items": [
{
"end_time": "08:45",
"period_no": 1,
"start_time": "08:00"
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_request | Invalid Request |
| 401 | authentication is required | Unauthorized |
| 403 | permission denied | Forbidden |
| 404 | term_not_found | Not Found |
| 500 | internal_error | Internal Server Error |