Skip to content

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 ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
500internal_errorInternal 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) ​

FieldTypeRequired
namestringYes
term_codestringYes
week1_mondaystringYes
weeksintegerYes
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 ​

StatusCodeDetail
400invalid_requestInvalid Request
401authentication is requiredUnauthorized
403permission deniedForbidden
409invalid_requestConflict
500internal_errorInternal 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 ​

ParameterDescription
term_codePath parameter.

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "end_time": "08:45",
      "period_no": 1,
      "start_time": "08:00"
    }
  ]
}

Errors ​

StatusCodeDetail
401authentication is requiredUnauthorized
403permission deniedForbidden
404periods_not_configuredNot Found; Not Found
404term_not_foundNot Found; Not Found
500internal_errorInternal 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 ​

ParameterDescription
term_codePath parameter.

Request body (application/json) ​

FieldTypeRequired
periodsarray<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 ​

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