Kanorio

API reference

Quiz attempts

Management API: GET /sites/{id}/quiz-attempts, POST /sites/{id}/quiz-attempts/grant-retry

Base URL https://app.kanorio.com/api/v1ErrorsPagination

List quiz attempts

GET/sites/{id}/quiz-attempts
betacustomers:viewdefault (120/minute per token)

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 · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • deliverableIdstring · query

    Deliverable id. Get it from deliverables.list.

  • unitIdstring · query

    Quiz unit id.

  • contactIdstring · query
  • limitinteger · query

    Maximum number of items to return, 1–100. Defaults to 20.

  • cursorstring · query

    Opaque cursor from the previous page's nextCursor. Omit for the first page.

Response 200

  • dataobject[]required
  • data[].idstringrequired
  • data[].contactIdstringrequired
  • data[].deliverableIdstringrequired
  • data[].unitIdstringrequired
  • data[].attemptNointegerrequired

    1-based per learner and unit.

  • data[].mode"graded" | "practice"required
  • data[].scoreintegerrequired

    0-100.

  • data[].correctinteger | nullrequired
  • data[].totalinteger | nullrequired
  • data[].passingPercentinteger | nullrequired

    Passing score at the time; null for practice attempts and attempts from before snapshots.

  • data[].passedbooleanrequired

    Always true for practice attempts.

  • data[].createdAtstringrequired

    ISO-8601 timestamp with timezone, e.g. 2026-10-05T12:34:56.789Z.

  • data[].perQuestionobjectrequired

    Question id → correct.

  • data[].answersobjectrequired

    Question id → chosen option ids, or the typed answer for short_text/numeric questions.

  • hasMorebooleanrequired

    True when another page exists; pass nextCursor to fetch it.

  • nextCursorstring | nullrequired

    Cursor for the next page, or null on the last page.

Errors

  • FORBIDDEN 403
  • INVALID_CURSOR 400

MCP tool quiz_attempts_list

curlTypeScript
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"
Response
{
  "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

POST/sites/{id}/quiz-attempts/grant-retry
betacustomers:managedefault (120/minute per token)

Give 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 · pathrequired

    Website id. Get it from sites.list or from sites.create.

Request body

  • deliverableIdstringrequired

    Deliverable id. Get it from deliverables.list.

  • unitIdstringrequired

    Quiz unit id of that deliverable.

  • contactIdstringrequired

Response 200

  • contactIdstringrequired
  • unitIdstringrequired
  • attemptsUsedintegerrequired
  • extraAttemptsintegerrequired

    Extra attempts granted so far, including this one.

  • maxAttemptsinteger | nullrequired

    Attempts allowed now (unit setting plus extra attempts).

  • attemptsLeftinteger | nullrequired
  • canAttemptbooleanrequired

Errors

  • FORBIDDEN 403
  • UNIT_NOT_FOUND 404
  • NOT_A_QUIZ 409
  • QUIZ_NOT_READY 409
  • CONTACT_NOT_FOUND 404
  • QUIZ_RETRY_NOT_APPLICABLE 422

MCP tool quiz_attempts_grant_retry

curlTypeScript
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"}'
Response
{
  "contactId": "contact_example01",
  "unitId": "unit_quiz_01",
  "attemptsUsed": 3,
  "extraAttempts": 1,
  "maxAttempts": 4,
  "attemptsLeft": 1,
  "canAttempt": true
}