更新日誌

/v1 在同一個版本內只做加法演進：可以新增選填的請求欄位、回應欄位、端點、事件型態、列舉值與錯誤代碼；既有欄位永遠不會被改名、移除、改型別或改用途。

因此客戶端必須容忍未知欄位。回應與 Webhook payload 都可能出現尚未見過的欄位，遇到時忽略即可，不應視為錯誤。

破壞性變更會以新的路徑版本（/v2）發布，/v1 持續運作至公告的日落日期。進入淘汰階段時，回應會帶有 Deprecation、Sunset 與 Link 標頭。

2026-08-24 — 首次發布

/v1 的首個公開版本。此後合約的每一次變更都會記錄於本頁。

以下為本版本涵蓋的範圍。

題庫與考試

題目支援四種題型：fill_in_blank（一格或多格填充）、short_answer、composition（作文、申論等長文作答）、nested（題組，最多三層）。題幹採 ProseMirror JSON 文件，可含文字、數學式、圖片與填充空格。
評分標準分為分析式評分（dimensions）與整體式評分（criteria）兩種結構，級距可用絕對分數或比例表示。標準可建立為跨題目共用的獨立物件，或內嵌於單一題目。
考試為有序的題目版本集合，建立當下內容即凍結。
題目與評分標準均為版本化資源，每次更新產生新的不可變版本；考試釘住題目版本，題目釘住評分標準版本。
題目、評分標準、考試皆可封存與取消封存，且不影響既有參照的解析。
學生名冊可將 student_ref 對應為可讀姓名，為選填功能。

提交與批閱

提交作答支援單筆與批次（一次最多 100 筆）建立，一律強制要求冪等鍵。
批閱為非同步作業，逐筆作答獨立進行。
批閱結果以版本累積：version 1 由 AI 產生，其後為人工覆核版本。結果依評分方法帶有 dimensions、criteria 或 blanks 細目，另可帶 penalties。
人工覆核以 expected_version 樂觀鎖防止覆蓋他人的修改，並強制記錄 reason。

事件與維運

Webhook 提供以下事件：submission.created／completed／failed，以及 response.grading_started／grading_completed／grading_failed／evaluation_revised。
遞送採至少一次原則，初次遞送加最多 5 次重試，並具備端點斷路器與死信佇列。
所有錯誤皆以統一的錯誤物件回應，並帶有 request_id 供追蹤。
API 金鑰的管理、Webhook 設定、組織設定與批閱重新排程僅能於 Studio 中操作。

尚未提供

掃描答案卷處理、多選題與 OMR 批閱，以及數學答案的 math_match 判定尚在規劃中，詳見未來規劃。