Skip to main content
班级是 TaskNeo 中主要的组织单元。每个班级都有一个 Owner、可选的 Admin 以及成员。每位用户在注册时还会自动获得一个个人班级（自己的私有工作区）。
所有班级接口都需要有效的 Authorization: Bearer <token> 头。

​
GET /classes

返回认证用户所属的所有班级，包括个人班级和所有共享班级。 Response — 200 OK 班级摘要对象数组。
​
id
string
required
班级 UUID。
​
name
string
required
班级名称。
​
description
string
可选描述。
​
color
string
required
十六进制颜色值，例如 #6366f1。
​
isPersonal
boolean
required
用户个人班级时为 true。
​
ownerId
string
required
班级 Owner 的 UUID。
​
schoolId
string
关联学校 UUID，或 null。
​
inviteCode
string
邀请码。仅 OWNER 和 ADMIN 可见。
​
myRole
string
required
你在该班级中的角色：OWNER、ADMIN 或 MEMBER。
​
memberCount
integer
required
成员总数。
​
createdAt
string
required
ISO 8601 UTC 时间戳。
curl https://api.yourdomain.com/classes \
  -H "Authorization: Bearer <token>"

​
POST /classes

创建一个新的共享班级。认证用户会自动成为 OWNER，并生成邀请码。 Request body
​
name
string
required
Class name.
​
description
string
Optional description.
​
color
string
default:"#6366f1"
Hex color for the class badge (e.g. #f59e0b).
​
schoolId
string
Associate the class with a specific school. When set, only users from that school can join via invite code.
Response — 201 Created 返回创建的班级摘要对象（结构与 GET /classes 的条目相同）。 
curl -X POST https://api.yourdomain.com/classes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CS101 — Introduction to Programming",
    "description": "Fall 2025 cohort",
    "color": "#6366f1"
  }'

​
GET /classes/:classId

获取单个班级的详情。你必须是该班级成员。 Path parameters
​
classId
string
required
班级 UUID。
Response — 200 OK 返回班级摘要对象。 Error codes
状态何时发生
403 Forbidden你不是该班级成员。
404 Not Found班级不存在。
curl https://api.yourdomain.com/classes/c1a2b3c4-... \
  -H "Authorization: Bearer <token>"

​
PATCH /classes/:classId

更新班级名称、描述或颜色。需要 OWNER 或 ADMIN 角色。 Path parameters
​
classId
string
required
班级 UUID。
Request body
​
name
string
新的班级名称。
​
description
string
新的描述。传入 null 可清空。
​
color
string
新的十六进制颜色值。
Response — 200 OK 返回更新后的班级摘要对象。 Error codes
状态何时发生
403 Forbidden权限不足（必须是 OWNER 或 ADMIN）。
curl -X PATCH https://api.yourdomain.com/classes/c1a2b3c4-... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "CS101 — Intro to Programming (Renamed)"}'

​
DELETE /classes/:classId

删除班级及其所有任务。只有 OWNER 可以删除班级。个人班级不能删除。
此操作不可逆。所有任务及其附件都会被删除。成员提交记录会被保留。
Path parameters
​
classId
string
required
班级 UUID。
Response — 204 No Content Error codes
状态何时发生
403 Forbidden权限不足，或正在尝试删除个人班级。
curl -X DELETE https://api.yourdomain.com/classes/c1a2b3c4-... \
  -H "Authorization: Bearer <token>"

​
POST /classes/join

使用邀请码加入班级。 Request body
​
inviteCode
string
required
班级 Owner 或 Admin 分享的邀请码。
Response — 200 OK 返回已加入班级的摘要对象。 Error codes
状态何时发生
403 Forbidden该班级限制为特定学校加入，而你的学校不匹配。
404 Not FoundInvite code is invalid or has been refreshed.
409 ConflictYou are already a member of this class.
curl -X POST https://api.yourdomain.com/classes/join \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"inviteCode": "XKCD42"}'

​
GET /classes/:classId/members

列出班级中的所有成员。你必须是该班级成员。 Path parameters
​
classId
string
required
班级 UUID。
Response — 200 OK 班级成员对象数组。
​
userId
string
required
成员用户 UUID。
​
nickname
string
显示名称，或 null。
​
avatarHash
string
required
用于 Gravatar 查找的用户邮箱 SHA-256 十六进制哈希。
​
role
string
required
成员角色：OWNER、ADMIN 或 MEMBER。
​
joinedAt
string
required
用户加入时的 ISO 8601 UTC 时间戳。
Error codes
状态何时发生
403 Forbidden你不是该班级成员。
curl https://api.yourdomain.com/classes/c1a2b3c4-.../members \
  -H "Authorization: Bearer <token>"

​
PATCH /classes/:classId/members/:userId

更改成员角色。只有 OWNER 可以将成员提升为 ADMIN，或将 ADMIN 降为 MEMBER。 Path parameters
​
classId
string
required
班级 UUID。
​
userId
string
required
要更新的成员 UUID。
Request body
​
role
string
required
新角色：ADMIN 或 MEMBER。不能直接设为 OWNER - 请改用所有权转移接口。
Response — 200 OK 返回更新后的班级成员对象。 Error codes
状态何时发生
403 Forbidden权限不足。只有 OWNER 可以更改角色。
curl -X PATCH https://api.yourdomain.com/classes/c1a2b3c4-.../members/b2c3d4e5-... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "ADMIN"}'

​
DELETE /classes/:classId/members/:userId

从班级中移除成员。规则如下：
  • OWNER 和 ADMIN 可以移除 MEMBER。
  • OWNER 可以移除 ADMIN。
  • 不能移除 OWNER（请先转移所有权）。
  • 任何成员都可以用此接口移除自己（离开班级）。
Path parameters
​
classId
string
required
班级 UUID。
​
userId
string
required
要移除的成员 UUID。
Response — 204 No Content Error codes
状态何时发生
403 Forbidden权限不足，或尝试移除 OWNER。
curl -X DELETE https://api.yourdomain.com/classes/c1a2b3c4-.../members/b2c3d4e5-... \
  -H "Authorization: Bearer <token>"

​
POST /classes/:classId/transfer

将班级所有权转移给其他成员。只有当前 OWNER 可以执行此操作。新 Owner 会被提升为 OWNER，原 Owner 会被降为 ADMIN。该操作是原子的。 Path parameters
​
classId
string
required
班级 UUID。
Request body
​
newOwnerId
string
required
要转移所有权给的成员 UUID。该成员必须已经是班级成员。
Response — 200 OK 返回更新后的班级摘要对象。 Error codes
状态何时发生
400 Bad Request目标用户不是该班级成员。
403 Forbidden你不是 OWNER。
curl -X POST https://api.yourdomain.com/classes/c1a2b3c4-.../transfer \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"newOwnerId": "b2c3d4e5-..."}'

​
POST /classes/:classId/invite-code

为班级生成新的邀请码。旧邀请码会立即失效。需要 OWNER 或 ADMIN 角色。 Path parameters
​
classId
string
required
班级 UUID。
Response — 200 OK
​
inviteCode
string
required
新的邀请码。
Error codes
状态何时发生
403 Forbidden权限不足（必须是 OWNER 或 ADMIN）。
curl -X POST https://api.yourdomain.com/classes/c1a2b3c4-.../invite-code \
  -H "Authorization: Bearer <token>"