POST /api/v1/submission-reviews/{submissionId}/decision
Record your verdict on the attempt you took in review. Changes requested and rejection require nonblank feedback.
Send x-api-key. The school and actor come from the verified key; body identities cannot override them. A verified school member with current review responsibility: organization reviewer, program reviewer, or coach assigned to the relevant enrollment/program as permitted by the school. Organization role alone does not replace review scope.
| Parameter | Type | Required | Description |
|---|
submissionId | UUID | yes | Resource in the authorized school and permitted scope. |
Idempotency-Key is required. Reuse it only for the identical target and payload. X-Correlation-Id is optional.
Request body
decision: validated, changes_requested or rejected. Optional feedback and expectedCorrections: nullable strings, each at most 4000 characters. Changes requested and rejected require nonblank feedback.
curl -X POST "https://www.cohorte.io/api/v1/submission-reviews/11111111-1111-4111-8111-111111111111/decision" \
-H "x-api-key: $COHORTE_API_KEY" \
-H "Idempotency-Key: pedagogy-example-001" \
-H "Content-Type: application/json" \
-d '{"decision": "changes_requested", "feedback": "Please explain the assumptions", "expectedCorrections": "Add the assumptions section"}'
200 returns the result. 400: invalid input or forbidden state transition. 401: invalid key. 403: submission absent from the authorized school/review scope, or insufficient current permission. 409: idempotency key conflicts with another or unverifiable intention.
replayed is a top-level boolean beside data and correlationId, not nested inside the resource.
submission, review and reviewerName; verdict side effects and notifications occur only once. Dates are ISO date-time strings or null.
{
"success": true,
"replayed": false,
"data": {
"submission": {
"id": "11111111-1111-4111-8111-111111111111",
"enrollmentId": "22222222-2222-4222-8222-222222222222",
"deliverableId": "33333333-3333-4333-8333-333333333333",
"previousSubmissionId": null,
"status": "changes_requested",
"comment": "Ready for review",
"attachments": [
{
"kind": "link",
"url": "https://example.com/work"
}
],
"submittedAt": "2026-10-16T08:00:00.000Z",
"createdAt": "2026-10-16T08:00:00.000Z",
"updatedAt": "2026-10-16T08:00:00.000Z"
},
"review": {
"id": "44444444-4444-4444-8444-444444444444",
"submissionId": "11111111-1111-4111-8111-111111111111",
"decision": "changes_requested",
"feedback": "Please explain the assumptions",
"expectedCorrections": "Add the assumptions section",
"createdAt": "2026-10-16T08:00:00.000Z"
},
"reviewerName": "Sam Dupont"
},
"correlationId": "22222222-2222-4222-8222-222222222222"
}
An identical retry uses the original claim after checking current permissions. Reusing a key for another target or payload conflicts. Read current state before issuing a new intention.
A verdict requires explicit reviewer instruction. The reviewer who took the attempt owns its decision; other scoped reviewers cannot decide it.
