提交 Submission

提交是一位學生對一份考試的完整作答集合，建立後不可修改，並以每題為單位非同步批閱。

列出提交

回傳提交摘要，不含內嵌的 responses。

認證方式

bearerAuth submissions:read

認證Bearer <token>

Authorization: Bearer sk_live_…

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

位置: header

Scope: submissions:read

查詢參數

exam_id?string

student_ref?string

custom_id?string

status?string

Value in

"pending"
"processing"
"completed"
"failed"

created_after?string

Formatdate-time

created_before?string

Formatdate-time

sort?string

排序欄位，前綴 - 為遞減、+ 或無前綴為遞增，以逗號分隔可指定多個欄位（例如 -created_at,status）。無法辨識的欄位名會得到 400 ERR_VALIDATION_FAILED，不會被忽略。

預設為 -created_at，即最新建立的排在最前面。 游標分頁的頁面邊界取決於排序，因此順序是有定義的而非未指定。

批閱結果版本歷史與覆核清單另有各自的預設（分別為 -version 與 -graded_at），

Default"-created_at"

limit?integer

每頁筆數，最大 100。

Rangevalue <= 100

Default20

cursor?string

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

回應內容

`application/json`

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

{  "data": [    {      "id": "string",      "exam_id": "string",      "student_ref": "string",      "custom_id": "string",      "source": "string",      "status": "string",      "response_count": 0,      "summary": {        "total_responses": 0,        "completed": 0,        "failed": 0,        "total_score": 0,        "max_score": 0      },      "created_at": "2019-08-24T14:15:22Z",      "completed_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  }}

提交一位學生的作答

提交作答並開始批閱。目標考試必須是 active。

responses 必須完全覆蓋考試的批閱對象：一般題目即題目本身，題組則是它的每一個末端子題，各自恰好一筆作答；每個 ref 都要出現且不可重複。應送出的筆數請看考試的 gradeable_count。

學生沒作答的對象不是省略，而是送出一筆空白作答：text 型別、 doc 為空（{"type": "doc", "content": [{"type": "paragraph"}]}），如此一份提交永遠是完整的作答集合。

送出非批閱對象的 ref（包含題組本身的 ref）、重複的 ref，或漏掉某個對象，都會讓整個請求以 400 ERR_VALIDATION_FAILED 被拒絕。

Idempotency-Key 標頭在此端點是必填。

認證方式

bearerAuth submissions:create

認證Bearer <token>

Authorization: Bearer sk_live_…

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

位置: header

Scope: submissions:create

標頭參數

Idempotency-Key*string

必填。 由客戶端產生、用於唯一識別該邏輯操作的字串，UUID 或結構化字串皆可。

24 小時內：同金鑰同內容會重播原始回應，所以網路失敗後重送永遠安全；同金鑰不同內容會以 409 ERR_DUPLICATE_TXID 遭拒，一把金鑰永久對應一個操作，新的操作要用新的金鑰。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

exam_id*string

student_ref?string

客戶端系統中的學生識別碼，以不透明字串儲存並原樣回傳。

roster_id?string

選填。指定一份學生名冊，供覆核介面把 student_ref 解析為姓名。純顯示用途：它不會進入批閱引擎，也不影響分數。

需要搭配 student_ref，單獨提供會得到 400。名冊中是否存在該 student_ref 不會被驗證，缺席時照常批閱、只是姓名解析不到。

custom_id?string

responses*array<>

metadata?

回應內容

`application/json`

curl -X POST "https://example.com/submissions" \  -H "Idempotency-Key: submission-s0042-exam_kQXzTR-20260302" \  -H "Content-Type: application/json" \  -d '{    "exam_id": "exam_kQXzTR",    "student_ref": "student_0042",    "roster_id": "ros_7hK2Qn",    "custom_id": "midterm-0042",    "responses": [      {        "question_ref": "q_mN4pXe:1",        "answer": {          "type": "fill_in",          "entries": [            {              "blank_id": "mockBlank4hq2wznd8fpr",              "doc": {                "type": "doc",                "content": [                  {                    "type": "paragraph",                    "content": [                      {                        "type": "text",                        "text": "類囊體膜"                      }                    ]                  }                ]              }            }          ]        }      },      {        "question_ref": "q_7g2NkP:2",        "answer": {          "type": "text",          "doc": {            "type": "doc",            "content": [              {                "type": "paragraph",                "content": [                  {                    "type": "text",                    "text": "光反應在類囊體膜產生 ATP 與 NADPH，暗反應在基質固定 CO₂……"                  }                ]              }            ]          }        }      }    ]  }'

{  "data": {    "id": "string",    "exam_id": "string",    "student_ref": "string",    "roster_id": "string",    "custom_id": "string",    "source": "direct",    "status": "pending",    "response_count": 0,    "responses": [      {        "id": "string",        "question_ref": "string",        "answer": {          "type": "text",          "doc": {            "type": "doc",            "content": [              {}            ]          }        },        "status": "pending",        "evaluation": {          "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"        },        "eta": 0,        "created_at": "2019-08-24T14:15:22Z"      }    ],    "summary": {      "total_responses": 0,      "completed": 0,      "failed": 0,      "total_score": 0,      "max_score": 0    },    "eta": 0,    "metadata": {},    "created_at": "2019-08-24T14:15:22Z",    "completed_at": "2019-08-24T14:15:22Z"  }}

批次提交（最多 100 筆）

一次建立最多 100 筆提交。

冪等性是逐筆的：每筆都必須帶 idempotency_key 內容欄位（不使用 Idempotency-Key 標頭）。

批次採部分成功模式：合法的項目照常建立並排入批閱，不合法的逐一回報而不影響整批，所以整個呼叫回 200 而不是錯誤。務必逐筆檢查 results[].status。

認證方式

bearerAuth submissions:create

認證Bearer <token>

Authorization: Bearer sk_live_…

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

位置: header

Scope: submissions:create

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

submissions*array<>

Itemsitems <= 100

回應內容

`application/json`

curl -X POST "https://example.com/submissions/batch" \  -H "Content-Type: application/json" \  -d '{    "submissions": [      {        "idempotency_key": "midterm-0042-v1",        "exam_id": "exam_kQXzTR",        "student_ref": "student_0042",        "responses": [          {            "question_ref": "q_mN4pXe:1",            "answer": {              "type": "fill_in",              "entries": [                {                  "blank_id": "mockBlank4hq2wznd8fpr",                  "doc": {                    "type": "doc",                    "content": [                      {                        "type": "paragraph",                        "content": [                          {                            "type": "text",                            "text": "類囊體膜"                          }                        ]                      }                    ]                  }                }              ]            }          },          {            "question_ref": "q_7g2NkP:2",            "answer": {              "type": "text",              "doc": {                "type": "doc",                "content": [                  {                    "type": "paragraph"                  }                ]              }            }          }        ]      }    ]  }'

{  "data": {    "batch_id": "string",    "total": 0,    "succeeded": 0,    "failed": 0,    "results": [      {        "index": 0,        "idempotency_key": "string",        "status": "created",        "submission_id": "string",        "error": {          "code": "string",          "message": "string"        }      }    ]  }}

取得提交

responses 在每個狀態下都內嵌回傳，各自帶有 status，批閱完成後帶最新的 evaluation，所以一次查詢就能看到逐題進度。5 欄的 summary 與最上層 completed_at 只在提交 completed 時出現；尚未完成的作答帶 eta 而非 evaluation。

認證方式

bearerAuth submissions:read

認證Bearer <token>

Authorization: Bearer sk_live_…

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

位置: header

Scope: submissions:read

路徑參數

submission_id*string

回應內容

`application/json`

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

{  "data": {    "id": "string",    "exam_id": "string",    "student_ref": "string",    "roster_id": "string",    "custom_id": "string",    "source": "direct",    "status": "pending",    "response_count": 0,    "responses": [      {        "id": "string",        "question_ref": "string",        "answer": {          "type": "text",          "doc": {            "type": "doc",            "content": [              {}            ]          }        },        "status": "pending",        "evaluation": {          "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"        },        "eta": 0,        "created_at": "2019-08-24T14:15:22Z"      }    ],    "summary": {      "total_responses": 0,      "completed": 0,      "failed": 0,      "total_score": 0,      "max_score": 0    },    "eta": 0,    "metadata": {},    "created_at": "2019-08-24T14:15:22Z",    "completed_at": "2019-08-24T14:15:22Z"  }}

取得提交歷程

一份提交從建立、逐題批閱、評分結果到人工覆核的完整時序。

這是平台持久事件紀錄的唯讀投影，不是即時由現況拼湊出來的，並依呼叫者過濾可見層級，租戶金鑰只會取得 customer 事件。

認證方式

bearerAuth submissions:read

認證Bearer <token>

Authorization: Bearer sk_live_…

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

位置: header

Scope: submissions:read

路徑參數

submission_id*string

回應內容

`application/json`

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

{  "data": {    "submission_id": "string",    "source": "string",    "status": "string",    "events": [      {        "at": "2019-08-24T14:15:22Z",        "stage": "submission",        "type": "string",        "status": "string",        "reason_code": "string",        "outcome": "graded",        "message": "string",        "response_id": "string",        "question_ref": "string",        "evidence": [          {            "kind": "score",            "earned": 0,            "max": 0          }        ],        "visibility": "customer"      }    ]  }}

200application/json

201application/json

400application/json

404application/json

409application/json

413application/json

415application/json

429application/json

200application/json

400application/json

413application/json

415application/json

200application/json

404application/json

200application/json

404application/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`

`application/json`

`application/json`

`application/json`

`application/json`