批閱結果 Evaluation

批閱結果以版本累積：version 1 永遠是 AI 批閱，version 2 以上是人工覆核。

列出一份提交的覆核紀錄

這份提交中所有經人工覆核的作答，依 graded_at 由新到舊；覆核有 graded_at 而沒有 created_at，因此不適用一般列表的 -created_at 預設。這是批閱結果版本之上的即時檢視，從未被覆核的作答不會出現。

認證方式

bearerAuth evaluations:read

認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: evaluations:read

路徑參數

submission_id*string

查詢參數

limit?integer

每頁筆數，最大 100。

Rangevalue <= 100

Default20

cursor?string

前一頁回應中的 next_cursor。游標是不透明權杖，請勿解析或自行組合。持續翻頁直到 has_more 為 false。

回應內容

`application/json`

curl -X GET "https://example.com/submissions/sub_9Xw2Lp/evaluation-revisions"

{  "data": [    {      "response_id": "string",      "question_ref": "string",      "evaluation_id": "string",      "version": 0,      "score": {        "earned": 0,        "max": 0      },      "previous_score": {        "earned": 0,        "max": 0      },      "delta": 0,      "graded_by": "string",      "reason": "string",      "graded_at": "2019-08-24T14:15:22Z",      "method": "string"    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  }}

取得最新批閱結果

該筆作答目前（版本號最高）的批閱結果。注意路徑段是單數的 evaluation。

認證方式

bearerAuth evaluations:read

認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: evaluations:read

路徑參數

response_id*string

回應內容

`application/json`

curl -X GET "https://example.com/responses/resp_5Kc3Yv/evaluation"

{  "data": {    "id": "string",    "response_id": "string",    "version": 0,    "method": "rubric_grading",    "outcome": "graded",    "score": {      "earned": 0,      "max": 0    },    "feedback": "string",    "blanks": [      {        "key": "string",        "score": {          "earned": 0,          "max": 0        },        "outcome": "graded",        "feedback": "string"      }    ],    "dimensions": [      {        "key": "string",        "score": {          "earned": 0,          "max": 0        },        "feedback": "string"      }    ],    "criteria": [      {        "key": "string",        "level": 0,        "feedback": "string"      }    ],    "penalties": [      {        "code": "string",        "effect": "deduction",        "description": "string"      }    ],    "grader_revision": "string",    "review_suggested": true,    "reason": "string",    "graded_by": "string",    "graded_at": "2019-08-24T14:15:22Z"  }}

列出所有批閱結果版本

完整版本鏈，依 version 由新到舊；這是本端點的固定排序，並非一般列表的 -created_at 預設。這是標準的分頁列表，沒有額外包裝，目前生效的版本就是 data[0]。

認證方式

bearerAuth evaluations:read

認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: evaluations:read

路徑參數

response_id*string

查詢參數

limit?integer

每頁筆數，最大 100。

Rangevalue <= 100

Default20

cursor?string

前一頁回應中的 next_cursor。游標是不透明權杖，請勿解析或自行組合。持續翻頁直到 has_more 為 false。

回應內容

`application/json`

curl -X GET "https://example.com/responses/resp_5Kc3Yv/evaluation/history"

{  "data": [    {      "id": "string",      "response_id": "string",      "version": 0,      "method": "rubric_grading",      "outcome": "graded",      "score": {        "earned": 0,        "max": 0      },      "feedback": "string",      "blanks": [        {          "key": "string",          "score": {            "earned": 0,            "max": 0          },          "outcome": "graded",          "feedback": "string"        }      ],      "dimensions": [        {          "key": "string",          "score": {            "earned": 0,            "max": 0          },          "feedback": "string"        }      ],      "criteria": [        {          "key": "string",          "level": 0,          "feedback": "string"        }      ],      "penalties": [        {          "code": "string",          "effect": "deduction",          "description": "string"        }      ],      "grader_revision": "string",      "review_suggested": true,      "reason": "string",      "graded_by": "string",      "graded_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  }}

覆核批閱結果（產生新版本）

以新的批閱結果版本記錄一次人工修正。舊版本原封不動保留，完整版本鏈可稽核。

每次請求都必填 reason 與 expected_version（這次修正所依據的版本）。其餘欄位依這筆批閱結果帶了什麼細目而定，規則只有一條： 有構成總分的部分，就修正部分；沒有，才指定總分。

該筆批閱結果帶有	送出	會被拒絕
`dimensions`	`dimensions`（必填）：只列出要改的向度，其餘由伺服器沿用，總分由伺服器加總	`score`、`blanks`
`blanks`	`blanks`（必填）：同樣的稀疏 patch、同樣由伺服器加總	`score`、`dimensions`
`criteria`	`score.earned`（必填）：這種結果沒有構成總分的部分	`dimensions`、`blanks`、`criteria`

兩層的 max 一律不接受，它由題目決定。

expected_version 是樂觀鎖：唯有它仍等於該作答目前最新的版本時，覆核才會寫入。若期間另一位覆核者已先寫入新版本，請求會以 409 ERR_CONFLICT 被拒且不建立任何版本，因此過時的修正不可能悄悄蓋掉更新的結果。這也是唯一會發生衝突的情形： AI 不會重新批閱已存在的批閱結果，而重新排程只受理 failed 的作答，該作答本就沒有版本可依據。

覆核者不受評分標準的級距限制：級距是整數時他們仍可給 2.5 分。所以 version 2 以上的 score.earned 未必對應到任何級距。這是預期行為，因為級距描述的是引擎的判斷，而這個總分是人的判斷。

認證方式

bearerAuth evaluations:revise

認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權；缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: evaluations:revise

路徑參數

response_id*string

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

expected_version*integer

這次修正所根據的批閱結果版本，必須等於目前最新版本。

score?

新的總分。不接受 max。

僅在該筆批閱結果帶有 criteria 時接受：那種結果沒有構成總分的部分，所以總分只能由覆核者直接指定。帶有 dimensions 或 blanks 的結果 不接受它：那些總分由各部分加總得出，送出總分會得到 400，而非兩者取一。

dimensions?array<>

逐向度修正，僅在該筆批閱結果帶有 dimensions 時接受，且必填。

這是一個稀疏 patch：只列出要修改的向度，未列出的沿用前一版的 earned 與 feedback。伺服器據此加總得出新的總分，因此 Σ dimensions[].score.earned = score.earned 在每一個版本上都成立。

max 由伺服器推導；earned 必須落在該向度 [0, max] 之內。

blanks?array<>

逐格修正，僅在該筆批閱結果帶有 blanks 時接受，且必填。

這是一個稀疏 patch：只列出要修改的格子，未列出的格子沿用前一版的 earned 與 feedback。伺服器據此加總得出新的總分，因此 Σ blanks[].score.earned = score.earned 在每一個版本上都成立。

max 由伺服器推導；earned 必須落在該格 [0, max_score] 之內。覆核版本的格子不帶 outcome，那是引擎的判定，仍可在 version 1 讀到。

這與 dimensions 是同一條規則：有構成總分的部分，就修正部分；沒有，才指定總分。 拒收客戶端提供的總分，也讓那條無條件的加總不變式不可能從外部被破壞。

feedback?string

取代整體評語。省略時由前一版沿用。

reason*string

覆核理由，必填，寫入版本紀錄與稽核紀錄。

回應內容

`application/json`

curl -X POST "https://example.com/responses/resp_5Kc3Yv/evaluation/revise" \  -H "Content-Type: application/json" \  -d '{    "expected_version": 1,    "dimensions": [      {        "key": "內容正確性",        "score": {          "earned": 4.5        },        "feedback": "替代論證可接受，酌予提高。"      }    ],    "feedback": "學生以替代論證說明暗反應，內容大致正確。",    "reason": "學生以替代論證方式作答，原評分低估其正確性。"  }'

{  "data": {    "id": "string",    "response_id": "string",    "version": 0,    "method": "rubric_grading",    "outcome": "graded",    "score": {      "earned": 0,      "max": 0    },    "feedback": "string",    "blanks": [      {        "key": "string",        "score": {          "earned": 0,          "max": 0        },        "outcome": "graded",        "feedback": "string"      }    ],    "dimensions": [      {        "key": "string",        "score": {          "earned": 0,          "max": 0        },        "feedback": "string"      }    ],    "criteria": [      {        "key": "string",        "level": 0,        "feedback": "string"      }    ],    "penalties": [      {        "code": "string",        "effect": "deduction",        "description": "string"      }    ],    "grader_revision": "string",    "review_suggested": true,    "reason": "string",    "graded_by": "string",    "graded_at": "2019-08-24T14:15:22Z",    "previous_score": {      "earned": 0,      "max": 0    }  }}

200application/json

404application/json

200application/json

404application/json

200application/json

404application/json

200application/json

400application/json

404application/json

409application/json

413application/json

415application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`