API 參考
題目 Question
題目是組織自有的題庫資源，逐版本不可變：每次更新都產生新版本，考試則釘選特定版本。
每個題目一筆，取其最新版本。
認證方式
bearerAuth questions:read認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:read
查詢參數
type?string
| 值 | 說明 | 批閱方式 |
|---|---|---|
fill_in_blank | 填充，一格或多格 | 逐格判定（blank_grading） |
short_answer | 簡答，可含數學 | AI 依評分標準批閱（rubric_grading） |
composition | 作文、申論等長文作答 | AI 依評分標準批閱（rubric_grading） |
nested | 題組，共用題幹底下掛子題 | 本身不批閱，批閱的是它的末端子題 |
評分標準掛在真正被批閱的那一層：short_answer / composition 掛在題目上，
fill_in_blank 掛在每一個由 AI 判定的空格上，nested 任何一層都不掛。
Value in
- "fill_in_blank"
- "short_answer"
- "composition"
- "nested"
custom_id?string
不分大小寫的部分比對。
status?string
預設 active；傳 active,archived 可包含已封存題目。
Default
"active"rubric_ref?string
回答「哪些題目用了這套標準？」。接受兩種形式：
- 裸 id（
rub_zh_comp）比對釘選該標準任何版本的題目，為封存該標準前應執行的檢查。 - 版本化參照（
rub_zh_comp:2）只比對該版本，用來找出新標準發布後仍停留在舊版的題目。
內嵌評分標準的題目沒有參照，永遠不會被比對到。
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
curl -X GET "https://example.com/questions"{ "data": [ { "id": "string", "version": 0, "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": [ { "score": 0, "ratio": 0, "description": "string", "examples": [ null ], "metadata": {} } ] } ], "criteria": [ { "name": "string", "description": "string", "levels": [ { "ratio": 0, "description": "string", "examples": [ null ], "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" } ], "pagination": { "has_more": true, "next_cursor": "string" }}建立 version 1 的題目。
評分標準必須且只能有一種形式。 設定 scoring.rubric_ref 引用共用標準，
或設定 scoring.rubric 內嵌題目專屬標準；兩者皆給或皆不給都會回傳 400。
內嵌不會產生 rub_ 資源：它是儲存在這個題目版本上的值，沒有 id，
也不會出現在 GET /rubrics 之中。若 rubric_ref 寫成 "rub_x:latest"，
會在此解析為明確版本後儲存。
認證方式
bearerAuth questions:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:manage
標頭參數
Idempotency-Key?string
建議帶上。同一把金鑰配同樣的內容重送時，會重播原本儲存的回應 （連同原本的 2xx 狀態碼），不會重複建立。金鑰保留 24 小時。
請求內容
application/json
TypeScript 型別定義
在 TypeScript 中使用 request body 型別。
回應內容
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/questions" \ -H "Content-Type: application/json" \ -d '{ "custom_id": "photosynthesis-01", "type": "short_answer", "content": { "stem": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "請說明光合作用的光反應與暗反應。" } ] } ] } }, "scoring": { "max_score": 10, "rubric": { "dimensions": [ { "name": "內容正確性", "levels": [ { "score": 6, "description": "正確說明光反應與暗反應的過程與產物" }, { "score": 3, "description": "僅說明部分過程" }, { "score": 0, "description": "內容有重大錯誤" } ] }, { "name": "完整性", "levels": [ { "score": 4, "description": "涵蓋所有主要步驟" }, { "score": 2, "description": "涵蓋部分步驟" }, { "score": 0, "description": "缺少關鍵步驟" } ] } ] } } }'{ "data": { "id": "string", "version": 0, "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": [ { "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" } } ] }, "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" }}認證方式
bearerAuth questions:read認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:read
路徑參數
question_id*string
查詢參數
version?integer
指定版本；省略時取最新版本。
回應內容
application/json
application/json
curl -X GET "https://example.com/questions/q_7g2NkP"{ "data": { "id": "string", "version": 0, "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": [ { "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" } } ] }, "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" }}建立題目的新版本並回傳。舊版本完全不受影響：已釘選它的考試繼續用它批閱。
type 在建立時固定，不能更改。
送出的每個欄位都是整個取代，不做合併。 未送出的欄位由前一版沿用，
送出的欄位則完全以請求內容為準。所以更新 scoring 必須帶完整的 scoring 物件；
只送 {"scoring": {"max_score": 12}} 會產生一個沒有評分標準的版本，驗證因此失敗。
這也正是評分標準「二選一」得以維持的原因：因為 scoring 永遠整包送出，
要將題目從共用標準改為專屬標準（或反向調整），只需送出所要的那一種，
另一種因為不在請求裡而自然消失。
認證方式
bearerAuth questions:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:manage
路徑參數
question_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/questions/q_7g2NkP" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "string", "version": 0, "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": [ { "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" } } ] }, "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" }}讓題目退出題庫：不再出現在預設的 GET /questions 列表，也不能再被釘選進新的考試。
已經釘選的一切完全不受影響，現有考試中的 "q_abc:1" 照常解析，
該考試的提交批閱結果與先前完全相同。封存是題庫操作，不是內容變更：
不會產生新版本，status 屬於整個題目而非某個版本。題目永遠不會被硬刪除。
認證方式
bearerAuth questions:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:manage
路徑參數
question_id*string
回應內容
application/json
application/json
application/json
curl -X POST "https://example.com/questions/q_7g2NkP/archive"{ "data": { "id": "string", "version": 0, "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": [ { "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" } } ] }, "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" }}認證方式
bearerAuth questions:manage認證Bearer <token>
Authorization: Bearer sk_live_…
每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；
缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。
位置: header
Scope: questions:manage
路徑參數
question_id*string
回應內容
application/json
application/json
application/json
curl -X POST "https://example.com/questions/q_7g2NkP/unarchive"{ "data": { "id": "string", "version": 0, "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": [ { "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" } } ] }, "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" }}