API 參考
考試 Exam
考試是一組被凍結的題目版本，提交作答時以考試 id 指定。建立當下內容即固定，之後只能修改標籤欄位。
回傳考試摘要，不含題目內容；改以 question_count、gradeable_count 與 max_score 表示。
認證方式
bearerAuth exams:read認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:read
查詢參數
name?string
以不分大小寫的子字串比對考試名稱，與評分標準、名冊的 ?name= 同一套規則。
custom_id?string
以不分大小寫的部分比對尋找你自己系統中的識別碼。
收到 409 ERR_DUPLICATE 時可以用它找出佔用的那一份考試；
部分比對也可能一併回傳相近的識別碼，需要確切值時請自行比對。
要確認某個 custom_id 是否已被使用，請以建立請求的 409 回應為準。
status?string
active、archived，或以逗號分隔兩者以取得完整歷史。
Default
"active"sort?string
排序欄位，前綴 - 為遞減、+ 或無前綴為遞增，以逗號分隔可指定多個欄位
（例如 -created_at,status）。無法辨識的欄位名會得到 400 ERR_VALIDATION_FAILED，
不會被忽略。
預設為 -created_at，即最新建立的排在最前面。 游標分頁的頁面邊界取決於排序，
因此順序是有定義的而非未指定。
批閱結果版本歷史與覆核清單另有各自的預設（分別為 -version 與 -graded_at），
Default
"-created_at"limit?integer
每頁筆數，最大 100。
Range
value <= 100Default
20cursor?string
前一頁回應中的 next_cursor。游標是不透明權杖，請勿解析或自行組合。
持續翻頁直到 has_more 為 false。
回應內容
application/json
application/json
application/json
curl -X GET "https://example.com/exams"{ "data": [ { "id": "string", "custom_id": "string", "name": "string", "status": "active", "question_count": 0, "gradeable_count": 0, "max_score": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "has_more": true, "next_cursor": "string" }}以版本化的題目參照組成一份考試。考試建立後即為 active，可立即接受提交，
沒有另外的啟用步驟。
questions 是參照字串陣列。寫入時 :latest 會就地解析成明確版本並固定下來，
之後不再重新解析，這是「同一份考試永遠以同一份內容批閱」的依據。
已封存的題目或評分標準不能被釘選。
認證方式
bearerAuth exams:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:manage
標頭參數
Idempotency-Key?string
建議帶上。同一把金鑰配同樣的內容重送時，會重播原本儲存的回應 （連同原本的 2xx 狀態碼），不會重複建立。金鑰保留 24 小時。
請求內容
application/json
TypeScript 型別定義
在 TypeScript 中使用 request body 型別。
回應內容
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/exams" \ -H "Content-Type: application/json" \ -d '{ "name": "期中考 - 生物", "custom_id": "midterm-bio-2026", "description": "高一生物期中測驗", "questions": [ "q_mN4pXe:1", "q_7g2NkP:latest" ], "metadata": { "grade": "10" } }'{ "data": { "id": "string", "custom_id": "string", "name": "string", "description": "string", "status": "active", "questions": [ { "question_ref": "string", "status": "active", "custom_id": "string", "type": "fill_in_blank", "content": { "stem": { "type": "doc", "content": [ {} ] }, "children": [ { "sub_id": "stringstringstringstr", "type": "fill_in_blank", "content": {}, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "examples": [], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "examples": [], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } } ] }, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" }, "metadata": {}, "created_at": "2019-08-24T14:15:22Z" } ], "gradeable_count": 0, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z" }}回傳完整考試，題目一律展開為釘選版本的快照，沒有 expand 參數，也不需要額外查詢。
展開止於題目：若題目引用共用評分標準，回傳的是 scoring.rubric_ref 參照字串而非標準內容。
釘選版本的內容不可變，取一次 GET /rubrics/{id}?version= 即可長期保存；
標準物件上的 status 等欄位則是即時的，重用保存副本前請重新驗證。
認證方式
bearerAuth exams:read認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:read
路徑參數
exam_id*string
回應內容
application/json
application/json
application/json
curl -X GET "https://example.com/exams/exam_kQXzTR"{ "data": { "id": "string", "custom_id": "string", "name": "string", "description": "string", "status": "active", "questions": [ { "question_ref": "string", "status": "active", "custom_id": "string", "type": "fill_in_blank", "content": { "stem": { "type": "doc", "content": [ {} ] }, "children": [ { "sub_id": "stringstringstringstr", "type": "fill_in_blank", "content": {}, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "examples": [], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "examples": [], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } } ] }, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" }, "metadata": {}, "created_at": "2019-08-24T14:15:22Z" } ], "gradeable_count": 0, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z" }}只能修改標籤欄位，任何狀態下都可以。這些欄位不會傳給批閱引擎， 所以修改它們不可能改變分數或破壞稽核軌跡。
questions 不接受，考試內容在建立當下即凍結。
要用不同內容批閱，請建立新的考試。
認證方式
bearerAuth exams:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:manage
路徑參數
exam_id*string
請求內容
application/json
TypeScript 型別定義
在 TypeScript 中使用 request body 型別。
回應內容
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/exams/exam_kQXzTR" \ -H "Content-Type: application/json" \ -d '{ "name": "期中考 - 生物（補考）" }'{ "data": { "id": "string", "custom_id": "string", "name": "string", "description": "string", "status": "active", "questions": [ { "question_ref": "string", "status": "active", "custom_id": "string", "type": "fill_in_blank", "content": { "stem": { "type": "doc", "content": [ {} ] }, "children": [ { "sub_id": "stringstringstringstr", "type": "fill_in_blank", "content": {}, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "examples": [], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "examples": [], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } } ] }, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" }, "metadata": {}, "created_at": "2019-08-24T14:15:22Z" } ], "gradeable_count": 0, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z" }}active → archived。已封存的考試停止接受提交，但仍可讀取，歷史提交也照常解析。
無請求內容。
認證方式
bearerAuth exams:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:manage
路徑參數
exam_id*string
回應內容
application/json
application/json
application/json
curl -X POST "https://example.com/exams/exam_kQXzTR/archive"{ "data": { "id": "string", "custom_id": "string", "name": "string", "description": "string", "status": "active", "questions": [ { "question_ref": "string", "status": "active", "custom_id": "string", "type": "fill_in_blank", "content": { "stem": { "type": "doc", "content": [ {} ] }, "children": [ { "sub_id": "stringstringstringstr", "type": "fill_in_blank", "content": {}, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "examples": [], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "examples": [], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } } ] }, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" }, "metadata": {}, "created_at": "2019-08-24T14:15:22Z" } ], "gradeable_count": 0, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z" }}archived → active，並清除 archived_at。
內容仍然凍結，取消封存恢復的是可用性而非可編輯性。無請求內容。
認證方式
bearerAuth exams:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: exams:manage
路徑參數
exam_id*string
回應內容
application/json
application/json
application/json
curl -X POST "https://example.com/exams/exam_kQXzTR/unarchive"{ "data": { "id": "string", "custom_id": "string", "name": "string", "description": "string", "status": "active", "questions": [ { "question_ref": "string", "status": "active", "custom_id": "string", "type": "fill_in_blank", "content": { "stem": { "type": "doc", "content": [ {} ] }, "children": [ { "sub_id": "stringstringstringstr", "type": "fill_in_blank", "content": {}, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "examples": [], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "examples": [], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } } ] }, "scoring": { "max_score": 0, "blanks": [ { "blank_id": "stringstringstringstr", "max_score": 0, "method": "exact_match", "accepted": [ "string" ], "case_sensitive": false, "variant_sensitive": false, "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" } ], "rubric_ref": "string", "rubric": { "name": "string", "dimensions": [ { "name": "string", "description": "string", "weight": 0, "levels": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ "string" ], "metadata": {} } ] } ], "metadata": {} }, "reference_answer": "string" }, "metadata": {}, "created_at": "2019-08-24T14:15:22Z" } ], "gradeable_count": 0, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "archived_at": "2019-08-24T14:15:22Z" }}