學生名冊 Roster
學生名冊把提交上的不透明學生識別碼對應到可讀的姓名，供覆核介面顯示。
回傳摘要，不含名單本身（一份名冊可能有數千筆）；要取得名單請以 id 查詢單一名冊。
認證方式
bearerAuth rosters:readAuthorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: rosters:read
查詢參數
不分大小寫的子字串比對。
排序欄位，前綴 - 為遞減、+ 或無前綴為遞增，以逗號分隔可指定多個欄位
（例如 -created_at,status）。無法辨識的欄位名會得到 400 ERR_VALIDATION_FAILED，
不會被忽略。
預設為 -created_at，即最新建立的排在最前面。 游標分頁的頁面邊界取決於排序，
因此順序是有定義的而非未指定。
批閱結果版本歷史與覆核清單另有各自的預設（分別為 -version 與 -graded_at），
"-created_at"每頁筆數，最大 100。
value <= 10020前一頁回應中的 next_cursor。游標是不透明權杖，請勿解析或自行組合。
持續翻頁直到 has_more 為 false。
回應內容
application/json
curl -X GET "https://example.com/rosters"{ "data": [ { "id": "string", "name": "string", "entry_count": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "has_more": true, "next_cursor": "string" }}entries 為必填，可以是空陣列。每筆需要 student_ref，在同一份名冊內唯一；
name 選填。一份名冊最多 10,000 筆。
名冊是可變且不分版本的，刻意與題目、評分標準相反；名冊從不影響分數，因此沒有需要凍結的內容。
認證方式
bearerAuth rosters:manageAuthorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: rosters:manage
標頭參數
建議帶上。同一把金鑰配同樣的內容重送時，會重播原本儲存的回應 （連同原本的 2xx 狀態碼），不會重複建立。金鑰保留 24 小時。
請求內容
application/json
TypeScript 型別定義
在 TypeScript 中使用 request body 型別。
回應內容
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/rosters" \ -H "Content-Type: application/json" \ -d '{ "name": "2026 春季 - 七年級", "entries": [ { "student_ref": "student_0041", "name": "王小明" }, { "student_ref": "student_0042", "name": "陳美玲" }, { "student_ref": "student_0043" } ] }'{ "data": { "id": "string", "name": "string", "entries": [ { "student_ref": "string", "name": "string" } ], "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}名單一律內嵌回傳，沒有另外的分頁子集合。
認證方式
bearerAuth rosters:readAuthorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: rosters:read
路徑參數
回應內容
application/json
application/json
curl -X GET "https://example.com/rosters/ros_7hK2Qn"{ "data": { "id": "string", "name": "string", "entries": [ { "student_ref": "string", "name": "string" } ], "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}送出的每個欄位都是整個取代，送出 entries 即取代整份名單。
系統不提供單筆學生的端點，要增刪一位學生請送出調整後的完整名單。
與題目、評分標準不同，這不會產生新版本：名冊可變，修改立即生效，updated_at 隨之更新。
認證方式
bearerAuth rosters:manageAuthorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: rosters:manage
路徑參數
請求內容
application/json
TypeScript 型別定義
在 TypeScript 中使用 request body 型別。
回應內容
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/rosters/ros_7hK2Qn" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "string", "name": "string", "entries": [ { "student_ref": "string", "name": "string" } ], "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}名冊是本 API 中唯一真正被刪除、而非封存的資源。沒有任何內容透過名冊解析
（提交直接儲存自己的 student_ref），所以刪除不會改變任何既有分數，也不會破壞稽核軌跡。
不會因為仍被引用而拒絕。 提交上的 roster_id 會原樣留著，姓名解析退化為顯示
student_ref。若改為擋下刪除，由於提交永不刪除，任何用過的名冊都會被永久釘住，
正好抵消了「名冊可以真正刪除」這項設計的用意。
認證方式
bearerAuth rosters:manageAuthorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: rosters:manage
路徑參數
回應內容
application/json
curl -X DELETE "https://example.com/rosters/ros_7hK2Qn"