考試 Exam

考試（Exam）由一組有序的題目組成，且為學生提交的單位。其中的題目，均由版本化參照組成，建立考試時將固定確切的題目版本。

組卷

使用 POST /exams 端點建立考試。考試建立後將可以立即接受提交，且無法再修改題目組合（也沒有版本化的功能）。因此組卷請在客戶端完成後，一次送出。

{
  "name": "期中考 - 生物",
  "custom_id": "midterm-bio-2026",
  "description": "高一生物期中測驗",
  "questions": ["q_mN4pXe:1", "q_7g2NkP:latest"],
  "metadata": { "grade": "10" }
}

其中 questions 是題目版本化參照的陣列。題目的版本化參照在同一份考試中必須為唯一，同一個 question_ref 不得出現兩次。

已封存的題目或評分標準不能被使用，若引用了已封存的題目或評分標準，將會得到 400 錯誤，錯誤訊息並會指出何者已被封存。

當建立考試時，題目的版本可以使用 :latest 指定當下的最新版本。在建立當下系統會自動解析為明確的版本號並寫入。因此若送出上述請求時 q_7g2NkP 的最新版為 2，則形同建立時使用了 "q_7g2NkP:2" 版本化參照。

然而，考試建立與題目的版本更新可以獨立進行，因此有可能在查閱題目到建立考卷的時間差之中，該題目遭由其他使用者建立了未經預期的新版本，導致版本解析到該未經預期的最新版，而非查閱時的版本。因此仍建議，盡量不要使用 :latest，應以明確的版本號為主。

考試的 custom_id 可自訂，但必須唯一。與既有考試重複將會得到 409 ERR_DUPLICATE 錯誤。

更新考卷資訊

考卷有部分資訊欄位，可在考卷建立後修改。使用 PATCH /exams/{id} 端點修改標籤欄位（name、description、custom_id、metadata）

若使用上述端點試圖修改 questions，將會得到 409 ERR_EXAM_LOCKED 錯誤。

若要以不同的題目組合進行批閱，請建立一份新的考試。

讀取考試

使用 GET /exams/{id} 端點讀取單一考試。讀取的回傳物件將會展開題目的欄位：

{
  "data": {
    "id": "exam_kQXzTR",
    "status": "active",
    "questions": [
      {
        "question_ref": "q_mN4pXe:1",
        "status": "active",
        "type": "fill_in_blank",
        "content": { "stem": { "…": "…" } },
        "scoring": { "max_score": 2, "…": "…" },
        "created_at": "2026-02-25T10:00:00Z"
      }
    ],
    "gradeable_count": 2
  }
}

若題目引用共用評分標準，則該題目將會在 scoring.rubric_ref 參數中回傳評分標準的版本化參照，而非展開的 Rubric 內容。若需要 Rubric 內容，請另行呼叫 GET /rubrics/{id} 端點取得。

列表

使用 GET /exams 端點以取得建立的考試列表。該列表不含題目內容，但會包含以下的摘要欄位：

question_count：該考試由幾個題目組成（一個題組計為一題）
gradeable_count：對該考試提交時，應送出幾筆作答（題組計入其末端子題）
max_score：考試總分

封存

POST /exams/{id}/archive 使考試停止接受提交，但仍可讀取。POST /exams/{id}/unarchive 可取消封存，使其恢復接受提交。

對已封存的考試提交會得到 409 ERR_EXAM_ARCHIVED 錯誤。

組卷

更新考卷資訊

讀取考試

列表

封存

相關

本頁內容