API reference
Quiz attempts
Management API: GET /sites/{id}/quiz-attempts, POST /sites/{id}/quiz-attempts/grant-retry
List quiz attempts, newest first, filtered by deliverable, unit and/or contact. Each attempt carries the snapshot taken when it was submitted (mode, passing score, per-question results and the learner's answers), so editing questions later does not change it; perQuestion keys are question ids of the unit's quiz body. Attempts from before snapshots existed have null correct/total/passingPercent and perQuestion regraded against the current questions. Errors: FORBIDDEN, INVALID_CURSOR.
Parameters
idstring · pathrequiredWebsite id. Get it from sites.list or from sites.create.
deliverableIdstring · queryDeliverable id. Get it from deliverables.list.
unitIdstring · queryQuiz unit id.
contactIdstring · querylimitinteger · queryMaximum number of items to return, 1–100. Defaults to 20.
cursorstring · queryOpaque cursor from the previous page's nextCursor. Omit for the first page.
Response 200
dataobject[]requireddata[].idstringrequireddata[].contactIdstringrequireddata[].deliverableIdstringrequireddata[].unitIdstringrequireddata[].attemptNointegerrequired1-based per learner and unit.
data[].mode"graded" | "practice"requireddata[].scoreintegerrequired0-100.
data[].correctinteger | nullrequireddata[].totalinteger | nullrequireddata[].passingPercentinteger | nullrequiredPassing score at the time; null for practice attempts and attempts from before snapshots.
data[].passedbooleanrequiredAlways true for practice attempts.
data[].createdAtstringrequiredISO-8601 timestamp with timezone, e.g. 2026-10-05T12:34:56.789Z.
data[].perQuestionobjectrequiredQuestion id → correct.
data[].answersobjectrequiredQuestion id → chosen option ids, or the typed answer for short_text/numeric questions.
hasMorebooleanrequiredTrue when another page exists; pass nextCursor to fetch it.
nextCursorstring | nullrequiredCursor for the next page, or null on the last page.
Errors
FORBIDDEN403INVALID_CURSOR400
MCP tool quiz_attempts_list
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/quiz-attempts?unitId=unit_quiz_01&contactId=contact_example01&limit=20" \
-H "Authorization: Bearer $KANORIO_TOKEN"{
"data": [
{
"id": "qa_01",
"contactId": "contact_example01",
"deliverableId": "dlv_example01",
"unitId": "unit_quiz_01",
"attemptNo": 2,
"mode": "graded",
"score": 100,
"correct": 3,
"total": 3,
"passingPercent": 70,
"passed": true,
"createdAt": "2026-10-06T08:00:00.000Z",
"perQuestion": {
"q1": true,
"q2": true,
"q3": true
},
"answers": {
"q1": [
"b"
],
"q2": [
"a",
"c"
],
"q3": [
"Taipei"
]
}
}
],
"hasMore": false,
"nextCursor": null
}Grant retry
/sites/{id}/quiz-attempts/grant-retryGive one learner one more attempt on one graded quiz (the unit's maxAttempts plus extra attempts granted so far). Only allowed when the quiz is graded with an attempt limit, the learner has used every attempt and has not passed; past attempts and statistics are kept. Returns the new allowance. Errors: FORBIDDEN, UNIT_NOT_FOUND, NOT_A_QUIZ, QUIZ_NOT_READY, CONTACT_NOT_FOUND, QUIZ_RETRY_NOT_APPLICABLE.
Parameters
idstring · pathrequiredWebsite id. Get it from sites.list or from sites.create.
Request body
deliverableIdstringrequiredDeliverable id. Get it from deliverables.list.
unitIdstringrequiredQuiz unit id of that deliverable.
contactIdstringrequired
Response 200
contactIdstringrequiredunitIdstringrequiredattemptsUsedintegerrequiredextraAttemptsintegerrequiredExtra attempts granted so far, including this one.
maxAttemptsinteger | nullrequiredAttempts allowed now (unit setting plus extra attempts).
attemptsLeftinteger | nullrequiredcanAttemptbooleanrequired
Errors
FORBIDDEN403UNIT_NOT_FOUND404NOT_A_QUIZ409QUIZ_NOT_READY409CONTACT_NOT_FOUND404QUIZ_RETRY_NOT_APPLICABLE422
MCP tool quiz_attempts_grant_retry
curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/quiz-attempts/grant-retry" \
-H "Authorization: Bearer $KANORIO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deliverableId":"dlv_example01","unitId":"unit_quiz_01","contactId":"contact_example01"}'{
"contactId": "contact_example01",
"unitId": "unit_quiz_01",
"attemptsUsed": 3,
"extraAttempts": 1,
"maxAttempts": 4,
"attemptsLeft": 1,
"canAttempt": true
}