API 레퍼런스

Progress

Management API: GET /sites/{id}/deliverables/{deliverableId}/progress, POST /sites/{id}/deliverables/{deliverableId}/progress/{contactId}/reset, POST /sites/{id}/deliverables/{deliverableId}/progress/{contactId}/complete

이 페이지는 영어로만 제공됩니다. API 레퍼런스, Webhook 이벤트, 변경 내역은 코드의 필드 이름·오류 코드와 맞추기 위해 영어로 제공합니다.

Base URL https://app.kanorio.com/api/v1Errors Pagination

List progress

GET/sites/{id}/deliverables/{deliverableId}/progress

betacustomers:viewdefault (120/minute per token)

List learners of one deliverable: progress (percent, completed, per-unit status), viewing (watchedSeconds, lastPlayedAt, per-unit unitCoverage) and downloads (count, last time). One row per contact that has an active entitlement; for DOWNLOAD deliverables look at downloads. Aggregated course and unit figures are in deliverables.insights and deliverable_units.insights. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, INVALID_CURSOR.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
deliverableIdstring · pathrequired
Deliverable id. Get it from deliverables.list.
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.
contactIdstring · query

Response 200

dataobject[]required
data[].contactIdstringrequired
data[].percentintegerrequired
data[].completedbooleanrequired
Completion snapshot: set the first time the completion rule is met and never reverts, even if units are added later.
data[].completedAtstring | nullrequired
data[].startedAtstring | nullrequired
First progress record.
data[].lastActivityAtstring | nullrequired
Latest progress report or download.
data[].certificateobject | nullrequired
data[].certificate.serialstringrequired
data[].certificate.issuedAtstringrequired
data[].unitsobjectrequired
data[].watchedSecondsintegerrequired
Wall-clock seconds of media playback across all units (2x speed for 10 minutes counts 5; rewatching counts again).
data[].lastPlayedAtstring | nullrequired
Latest media playback; null when the learner has only opened non-media units or downloaded files.
data[].unitCoverageobjectrequired
Per media unit: share of the file actually watched (union of watched ranges / duration, 0-100). Units without a duration or never played are omitted.
data[].downloadsobjectrequired
Download events across all units (every entitlement source counts).
data[].downloads.countintegerrequired
data[].downloads.lastAtstring | nullrequired
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
DELIVERABLE_NOT_FOUND 404
INVALID_CURSOR 400

MCP tool progress_list

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/deliverables/{deliverableId}/progress" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "data": [
    {
      "contactId": "contact_example01",
      "percent": 50,
      "completed": false,
      "completedAt": null,
      "startedAt": "2026-10-06T08:00:00.000Z",
      "lastActivityAt": "2026-10-06T08:00:00.000Z",
      "certificate": null,
      "units": {
        "unit_video01": "completed",
        "unit_text01": "in-progress"
      },
      "watchedSeconds": 1860,
      "lastPlayedAt": "2026-10-06T08:00:00.000Z",
      "unitCoverage": {
        "unit_video01": 94
      },
      "downloads": {
        "count": 2,
        "lastAt": "2026-10-06T08:00:00.000Z"
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Progress reset

POST/sites/{id}/deliverables/{deliverableId}/progress/{contactId}/reset

betacustomers:managedefault (120/minute per token)

Reset one learner on one deliverable: deletes their unit progress, quiz attempts and completion record so they start over. Certificates already issued are kept. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, CONTACT_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
deliverableIdstring · pathrequired
Deliverable id. Get it from deliverables.list.
contactIdstring · pathrequired

Response 200

contactIdstringrequired
percentintegerrequired
completedbooleanrequired
completedAtstring | nullrequired
unitsobjectrequired

Errors

FORBIDDEN 403
DELIVERABLE_NOT_FOUND 404
CONTACT_NOT_FOUND 404

MCP tool progress_reset

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/deliverables/{deliverableId}/progress/{contactId}/reset" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "contactId": "contact_example01",
  "percent": 0,
  "completed": false,
  "completedAt": null,
  "units": {}
}

Progress complete

POST/sites/{id}/deliverables/{deliverableId}/progress/{contactId}/complete

betacustomers:managedefault (120/minute per token)

Mark one learner complete on one deliverable on their behalf: every unit that counts toward completion is marked completed, the completion record is written (ruleType manual) and the certificate is issued when enabled. Errors: FORBIDDEN, DELIVERABLE_NOT_FOUND, CONTACT_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
deliverableIdstring · pathrequired
Deliverable id. Get it from deliverables.list.
contactIdstring · pathrequired

Response 200

contactIdstringrequired
percentintegerrequired
completedbooleanrequired
completedAtstring | nullrequired
unitsobjectrequired

Errors

FORBIDDEN 403
DELIVERABLE_NOT_FOUND 404
CONTACT_NOT_FOUND 404

MCP tool progress_complete

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/deliverables/{deliverableId}/progress/{contactId}/complete" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "contactId": "contact_example01",
  "percent": 100,
  "completed": true,
  "completedAt": "2026-10-06T08:00:00.000Z",
  "units": {
    "unit_video01": "completed",
    "unit_text01": "completed"
  }
}