← Lumi for institutions GUIDES FOR YOUR TEAM

API reference: every route, request and error

The AI tutor API for institutions: every route with its request, its answer and each error it can return, in the sandbox and live.

Last updated: 18 November 2026

Every route below answers JSON. Your server calls the routes with a key; the last group is called by the player and the console's review tab, and is here so their codes make sense. For the steps around these calls, read the Integration and Library guides first.

Basics

Addresses

EnvironmentAPI addressKeys
Sandbox (testing)https://staging.sketchmind.ai/v1sk_sandbox_…
Live (your real students)https://platform.sketchmind.ai/v1sk_live_…

The examples use two shell variables: $LUMI_API is the address for your environment and $LUMI_KEY your key. Call the API from your server only; a key must never reach a browser or an app.

export LUMI_API="https://staging.sketchmind.ai/v1"   # the live address when you go live
export LUMI_KEY="sk_sandbox_…"            # from your console's Integration page

Keys and scopes

Send the key on every call as Authorization: Bearer <key>. A key can do only what its scopes allow; you pick them when you make the key in the console.

ScopeWhat it allows
launchOpen lessons: ask for a launch link for a student.
learnersManage students: read a student, change their plan, pause or erase them.
libraryManage the library: import lessons and read what is ready.
usageRead numbers: the statement, lesson results, library coverage and each student's progress.

Limits and conventions

  • At most 120 requests a minute per key. Over it, the answer is 429 rate_limited with a Retry-After header and the same number in retryAfter and retryAfterSeconds.
  • Bodies are JSON, at most 1 MB.
  • An error answer is always { "error": "<code>" }, sometimes with more fields (named in each table below). Match on the code, never on a sentence.
  • Students and lessons are named by your ids: {userId} is your id for a student and {slug} is a Lesson ID. A student's own id on our side never appears.
  • Times are ISO 8601 in UTC. Days and months (lesson limits, statements) follow India time.

Errors any route can return

From the key check

StatusCodeWhat it means
401invalid_api_keyThe key is missing, mistyped or unknown.
401api_key_revokedThe key was turned off, or it was replaced and its 24 hours of grace are over. Use the new key.
403sandbox_key_not_acceptedA sandbox key was sent to the live address. Sandbox keys work only on the sandbox address.
403org_suspendedYour organisation is suspended. Write to us.
403insufficient_scopeThe key cannot do this. The answer's scope field names the scope it needs.
429rate_limitedMore than 120 requests a minute with this key. Wait for the seconds in Retry-After (also retryAfter and retryAfterSeconds in the body).
503partner_auth_unavailableWe could not check the key just now. Try again.

From reading the request

StatusCodeWhat it means
400invalid_jsonThe body is not valid JSON.
413body_too_largeThe body is over 1 MB.
415unsupported_media_typeThe body uses an encoding or character set we cannot read. Send plain UTF-8 JSON.
4xxbad_requestThe body could not be read, for example it was cut off part-way.
404not_foundNo route answers this path and method.
500internal_errorSomething failed on our side. Nothing more is said; try again, and write to us if it repeats.

Launching

Your server asks for a launch link each time a student opens a lesson.

POST /v1/launch

Launch a student. Finds the student by your id (or adds them the first time), applies the plan you name, checks what the plan allows today, and answers a launch link that works once, within five minutes.

Key scope: launch

Request

curl -X POST "$LUMI_API/launch" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "stu_48213",
    "entitlement": "school_plan",
    "mode": "library",
    "lessonId": "concave-mirror-images",
    "context": { "language": "hi-IN", "depth": "balanced", "difficulty": "standard", "delivery": "lean" },
    "attributes": { "cohort": "2027", "batch": "B4", "centre": "pune-1", "planCode": "annual" },
    "validTill": "2027-03-31",
    "consent": { "dpdpConsentAt": "2026-10-01T10:00:00Z", "guardianConsent": true }
  }'

Answer · 200

{
  "launchUrl": "https://embed-lumi.sketchmind.ai/#launch=…",
  "expiresIn": 300,
  "learner": {
    "entitlement": "school_plan",
    "caps": { "lessonsLeftToday": 4, "doubtsLeftToday": 20 }
  }
}
  • userId is required: your own id for the student, never a name, email or phone number.
  • mode is library (lessonId is the Lesson ID from your library) or ask (send ask: { topic, subject, questionText }, all optional).
  • entitlement is the plan's API name from your Plans page; leave it out to keep the student's current plan.
  • context is optional: exam, course, year, level, language, depth (quick, balanced, thorough), difficulty (gentle, standard, challenge) and delivery (anchored, lean, direct). Delivery only picks among a library lesson's recordings.
  • language takes a language name such as English (India), Hinglish or Hindi, a short id (hindi) or a locale tag (hi-IN, en-IN, hi-Latn for Hinglish). A language we do not teach in your environment is refused language_unsupported, and the answer lists the ones we do.
  • attributes holds only cohort, batch, centre and planCode. validTill is a date after which the plan ends. consent records the time of consent and whether a guardian agreed.
  • Never send a name, phone, email, date of birth, address or image anywhere in the body.
  • lessonsLeftToday is the smaller of today's lessons left and, on a trial plan, the trial's lessons left.
  • Every refusal is decided before anything is written: a refused launch adds no student and changes no stored setting.

Errors

StatusCodeWhat it means
400invalid_bodyThe body is not a JSON object.
400invalid_user_iduserId is missing or not a usable id: 1 to 128 letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit.
400pii_in_iduserId looks like an email or phone number. Send your own opaque id.
400pii_not_acceptedThe body carries personal data (a name, phone, email, date of birth, address or image). The field is named in the answer.
400invalid_modemode is not library or ask. The answer lists the allowed words.
400invalid_lesson_idA library launch without a lessonId.
400invalid_valid_tillvalidTill is not a date.
400invalid_deliverycontext.delivery is not anchored, lean or direct. The answer lists the allowed words.
400language_unsupportedNo language answers to context.language here. The answer lists the supported ones.
403unknown_entitlementThe plan you named is not one of your plans.
403language_not_entitledThe student's plan does not include the language this lesson would teach in. The answer lists the allowed ones.
403learner_suspendedThe student is paused, or was erased in the last 90 days.
403mode_not_allowedThe student's plan does not allow this mode (library or ask).
403trial_exhaustedThe student has used every lesson of their trial.
403lessons_per_dayThe student has used today's lessons. Counts start again at midnight, India time.
403lessons_pausedYour organisation's monthly limit is reached, so new lessons are paused. Lessons already running finish.
403org_suspendedYour organisation is suspended or closed.
403variant_not_availableThe lesson has approved recordings, but none in this language, depth, difficulty or delivery, and the lesson does not fall back to the nearest one.
404lesson_not_availableThe Lesson ID is unknown, hidden, retired, or has nothing approved yet.
409org_policy_missingYour organisation has no plans yet. We set the first ones up with you.
429rate_limitedThis student was launched 6 times in the last minute. Wait for Retry-After.
503learner_unavailableWe could not set up the student just now. Try again.
503launch_unavailableWe could not issue the link just now. Try again.

Students

Read and change the students your launches created. Your id is the only id; ours never appears.

GET /v1/learners/{userId}

Read a student. One student, by your id: their plan, who set it, what they have left today, and when they were first and last seen.

Key scope: learners

Request

curl -X GET "$LUMI_API/learners/stu_48213" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "userId": "stu_48213",
  "entitlement": "school_plan",
  "entitlementSetBy": "launch",
  "planInForce": "school_plan",
  "planSetInConsole": false,
  "validTill": "2027-03-31",
  "attributes": { "cohort": "2027", "batch": "B4", "centre": "pune-1", "planCode": "annual" },
  "consent": { "dpdpConsentAt": "2026-10-01T10:00:00Z", "guardianConsent": true },
  "status": "active",
  "firstSeenAt": "2026-10-02T09:12:00.000Z",
  "lastSeenAt": "2026-10-20T16:40:00.000Z",
  "launches": 31,
  "lessonsEver": 18,
  "caps": { "lessonsLeftToday": 4, "doubtsLeftToday": 20 }
}
  • entitlement is the plan your app (or this API) last named. planInForce is the plan that applies right now: a plan set for the student in the console while it lasts, else yours. planSetInConsole says which.
  • entitlementSetBy is launch, console, api or expiry.
  • status is active or suspended; an erased student also carries deletedAt.

Errors

StatusCodeWhat it means
400invalid_user_idThe id in the address is not usable.
400pii_in_idThe id in the address looks like an email or phone number.
404not_foundNo student has this id.

PATCH /v1/learners/{userId}

Change a student. Change a student's plan, attributes, end date or status. The answer is the student after the change, in the shape of Read a student.

Key scope: learners

Request

curl -X PATCH "$LUMI_API/learners/stu_48213" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entitlement": "school_plan_plus", "validTill": null, "status": "active" }'

Answer · 200

{
  "userId": "stu_48213",
  "entitlement": "school_plan_plus",
  "entitlementSetBy": "api",
  "planInForce": "school_plan_plus",
  "planSetInConsole": false,
  "attributes": { "cohort": "2027", "batch": "B4", "centre": "pune-1", "planCode": "annual" },
  "status": "active",
  "…": "the other fields of Read a student"
}
  • Send only the fields you change: entitlement, attributes (cohort, batch, centre, planCode — it replaces the stored set), validTill (a date; null clears it) and status (active or suspended).
  • A new plan applies from the student's next lesson. Re-sending the plan already stored changes nothing.
  • Refusals are checked in the order listed below, and nothing is written on a refusal.

Errors

StatusCodeWhat it means
400invalid_user_idThe id in the address is not usable.
400pii_in_idThe id in the address looks like an email or phone number.
400invalid_bodyThe body is not a JSON object.
400pii_not_acceptedThe body carries personal data. The field is named in the answer.
400unsupported_fieldThe body has a field this route does not change. The field is named in the answer.
400unknown_entitlementThe plan is not one of your plans.
400invalid_attributesattributes is not an object of the four allowed keys.
400invalid_valid_tillvalidTill is not a date or null.
400invalid_statusstatus is not active or suspended.
404not_foundNo student has this id.
410learner_deletedThe student was erased.

DELETE /v1/learners/{userId}

Erase a student. Erases the student at once: their profile, ratings and progress are deleted, their lessons are kept only as anonymous records, and their attributes are cleared. The id is held for 90 days, so a launch with it in that time is refused learner_suspended.

Key scope: learners

Request

curl -X DELETE "$LUMI_API/learners/stu_48213" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{ "userId": "stu_48213", "erased": true, "sessionsAnonymised": 12, "tombstoneDays": 90 }
  • Safe to repeat: erasing an erased student answers the same way.
  • The console has no erase button; this route is the way to erase.

Errors

StatusCodeWhat it means
400invalid_user_idThe id in the address is not usable.
400pii_in_idThe id in the address looks like an email or phone number.
404not_foundNo student has this id.

Library

Upload lessons and read what is ready. Folders are arranged in the console.

GET /v1/library

Read the library. Your folders and lessons: the folder tree in syllabus order, and every lesson with its recordings and their review state.

Key scope: library

Request

curl -X GET "$LUMI_API/library" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "nodes": [{ "nodeId": "…", "parentId": null, "kind": "…", "title": "Optics", "slug": "optics", "path": "optics", "order": 1, "status": "…" }],
  "lessons": [{
    "lessonId": "concave-mirror-images",
    "title": "Images in a concave mirror",
    "shape": "topic",
    "nodeId": "…",
    "order": 3,
    "examTags": ["JEE Main"],
    "variants": [{ "language": "Hindi", "depth": "balanced", "difficulty": "standard" }],
    "allowVariantFallback": true,
    "status": "ready",
    "approvedVariants": [{ "language": "Hindi", "depth": "balanced", "difficulty": "standard" }],
    "versions": [{ "versionId": "…", "variant": { … }, "n": 2, "state": "approved", "checkQuestions": 4, "pinned": false }]
  }]
}
  • Folders come parents first, then siblings in the order you set in the console, then by title in natural order (Chapter 2 before Chapter 10).
  • A folder archived in the console stays in the list with archived: true, so a lesson's nodeId never names a missing folder.
  • A lesson's nodeId never changes when its folder is moved or renamed; it is null for a lesson in no folder.
  • No API route changes folders: arrange them in the console.
  • Without page, limit, q, status or folder the answer is the whole library, exactly as above. With any of them it is one page, and the answer adds page (from 1), limit (1 to 100, default 25), total (how many lessons match) and hasMore (whether a later page has any). A page past the end has no lessons.
  • q matches a lesson's title or Lesson ID, the exact Lesson ID first. status keeps one status: draft, generating, partial, ready, retired or hidden. folder is a folder's nodeId or its path (an address a console move took it from still works) and keeps that folder and every folder below it; nodes then holds only that part of the tree.
  • versions=all (the default), approved or latest (each variant's newest approved recording) narrows every lesson's versions list. It pages nothing on its own, and approvedVariants always counts every version.

Errors

StatusCodeWhat it means
400invalid_pagepage is not a whole number from 1.
400invalid_limitlimit is not a whole number from 1 to 100.
400invalid_qq was sent more than once.
400invalid_statusstatus is not one of draft, generating, partial, ready, retired or hidden.
400invalid_folderNo folder has that nodeId or path.
400invalid_versionsversions is not all, approved or latest.

GET /v1/library/lessons/{slug}

Read one lesson. One lesson by its Lesson ID, in the same shape as a lesson in Read the library.

Key scope: library

Request

curl -X GET "$LUMI_API/library/lessons/concave-mirror-images" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "lessonId": "concave-mirror-images",
  "title": "Images in a concave mirror",
  "shape": "topic",
  "nodeId": "…",
  "order": 3,
  "examTags": ["JEE Main"],
  "variants": [{ "language": "Hindi", "depth": "balanced", "difficulty": "standard" }],
  "allowVariantFallback": true,
  "status": "ready",
  "approvedVariants": [{ "language": "Hindi", "depth": "balanced", "difficulty": "standard" }],
  "versions": [{ "versionId": "…", "variant": { … }, "n": 2, "state": "approved", "checkQuestions": 4, "pinned": false }]
}
  • A variant names delivery only when its row named one.

Errors

StatusCodeWhat it means
404not_foundNo lesson has this Lesson ID.

POST /v1/library/import

Upload a library file. Send your lesson file as text inside JSON. Without confirm it is a free check that changes nothing and lists what would happen. With confirm: true and the check's expect counts, it applies the file and starts the recordings.

Key scope: library

Request

# 1. The free check
curl -X POST "$LUMI_API/library/import" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "csv": "path,slug,title,shape,languages\noptics/mirrors,concave-mirror-images,Images in a concave mirror,topic,Hindi\n", "filename": "mirrors.csv" }'

# 2. Confirm, sending back the check's five counts
curl -X POST "$LUMI_API/library/import" \
  -H "Authorization: Bearer $LUMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "csv": "…the same file…", "confirm": true,
        "expect": { "jobs": 1, "rerecords": 0, "takenOff": 0, "moves": 0, "changes": 0 } }'

Answer · 200 (check) · 201 (confirm)

{
  "ok": true,
  "dryRun": true,
  "rowsTotal": 1,
  "accepted": [{ "row": 2, "slug": "concave-mirror-images", "title": "Images in a concave mirror", "variants": 1 }],
  "rejected": [],
  "jobsPlanned": 1,
  "jobsAlreadyQueued": 0,
  "jobsQueued": 0,
  "estimateMinutes": 12,
  "rerecords": 0,
  "expect": { "jobs": 1, "rerecords": 0, "takenOff": 0, "moves": 0, "changes": 0 },
  "structure": { "newFolders": [{ "path": "optics/mirrors", "title": "Mirrors" }], "moves": [], "changes": [], "moveExisting": false }
}
  • Send the file inside JSON: { csv, confirm?, filename?, moveExisting?, expect? }. A raw text/csv body is refused invalid_body.
  • The columns, and what an empty cell or a - means, are in the Library guide. One row makes one recording for each language × depth × difficulty (× delivery, when the row names one).
  • A rejected row carries a sentence that names the problem; the other rows still go ahead.
  • The confirm answers 201 with batchId and jobsQueued, and expect and structure say what was applied. Read its progress with Read an upload.
  • The same file again starts nothing new. A file that would start more than 2,000 recordings is refused whole, on the check too. One upload takes at most 500 rows.
  • moveExisting: true also moves existing lessons into the file's folders. Without it, a file only places new lessons.
  • estimateMinutes is our estimate of the time until the recordings are ready.

Errors

StatusCodeWhat it means
400invalid_csvThe file cannot be used as a whole: unreadable, empty, an unknown or missing column, more than 500 rows, more than 2,000 new recordings, or too many folders. detail says which.
400invalid_bodyThe body is not JSON with a csv text field.
400expect_requiredA confirm must send the check's expect counts. Run the check and send its expect back.
400invalid_expectexpect is not five whole numbers of zero or more.
409plan_changedThe library changed since your check, and the file would now do more than you confirmed. Nothing was written; run the check again. The answer carries the new counts.
409library_busySomeone else is changing the library right now (busy says who: upload, change or sketchmind). Try again after Retry-After.
409import_interruptedThe upload stopped part-way. The rows applied stay (rowsApplied, jobsQueued); run the check again to see what is left.
409recordings_pausedNew recordings are paused for your organisation this month. Write to us.
413csv_too_largeThe file is too large. Split it into smaller files.
500import_failedThe upload failed part-way on our side. The rows applied stay; run the check again.

GET /v1/library/batches/{batchId}

Read an upload. One upload's progress: how many rows were accepted and how its recordings are doing.

Key scope: library

Request

curl -X GET "$LUMI_API/library/batches/<batchId>" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "batchId": "…",
  "source": "api",
  "filename": "mirrors.csv",
  "rowsTotal": 40,
  "rowsAccepted": 38,
  "rejected": [{ "row": 7, "reason": "…" }],
  "jobsPlanned": 114,
  "jobsQueued": 114,
  "estimateMinutes": 90,
  "state": "running",
  "jobs": { "queued": 60, "running": 4, "done": 48, "failed": 2, "cancelled": 0 },
  "createdAt": "2026-10-21T08:00:00.000Z",
  "updatedAt": "2026-10-21T08:40:00.000Z"
}
  • state is dry_run, confirmed, running or done. jobs counts every recording of the upload by state.

No errors of its own beyond the ones any route can return.

GET /v1/library/batches/{batchId}/quality

Read an upload's checks. How an upload's recordings fared at our checks: how many came out clean, how many tries each lesson took to approval, and what still waits on you. Counts only.

Key scope: library

Request

curl -X GET "$LUMI_API/library/batches/<batchId>/quality" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "batchId": "…",
  "recordings": { "first": 114, "checked": 110 },
  "clean": 96,
  "criticals": { "total": 21, "checked": 131 },
  "approved": { "total": 88, "automatic": 52, "rounds": { "1": 70, "2": 14, "3": 3, "4": 1 }, "averageRounds": 1.3 },
  "fixes": { "made": 25, "automatic": 19, "perApproved": 0.3 },
  "openDisputes": 2,
  "waiting": 9
}
  • recordings.first is how many recordings the upload made, and checked how many of them have a finished check. clean is how many of those checked recordings had no critical problem.
  • criticals counts critical problems over every checked recording that grew from the upload: each first recording, the fixed recordings made from it, and the new recording made after a rejection.
  • approved counts lessons by how many recordings it took to reach their first approval (4 means four or more). averageRounds has one decimal, and is null when nothing is approved yet. automatic is how many approvals were made by approve-when-clean rather than by a person.
  • fixes.made is how many fixed recordings were made, automatic how many of them by an automatic fix, and perApproved how many fixes it took per approved lesson.
  • openDisputes is the problems waiting for your answer on recordings still in play. waiting is the lessons whose newest recording waits in review.
  • Worked out from the stored records each time you ask. It never shows money.

Errors

StatusCodeWhat it means
404not_foundNo upload of yours has this id.

Numbers

Counts only, never money. Staff and sandbox students stay out of the numbers.

GET /v1/usage

Read the statement. The statement: per month and per plan, counts in your contract's unit (active students or lessons). Counts only. Written each night, so it reads to last night.

Key scope: usage

Request

curl -X GET "$LUMI_API/usage?from=2026-09&to=2026-10" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "unit": "learner",
  "from": "2026-09",
  "to": "2026-10",
  "periods": [{
    "period": "2026-10",
    "status": "in_progress",
    "total": { "entitlement": null, "cycleActiveLearners": 812, "sessionsStarted": 5120, "sessions": { "library": 3900, "ask": 1220 }, "completed": 4310, "doubts": 9800, "minutes": 61200 },
    "lines": [{ "entitlement": "school_plan", "cycleActiveLearners": 790, "sessionsStarted": 4990, "sessions": { "library": 3800, "ask": 1190 }, "completed": 4200, "doubts": 9500, "minutes": 59800 }]
  }]
}
  • from and to are months (YYYY-MM, India time). from defaults to the current month, and to defaults to from.
  • status is in_progress (this month), settling (with finalOn, the date it becomes final) or final.
  • The total row also carries fair use (students over the question limit), excluded (staff and sandbox students) and, when there was any, sandbox: sandbox traffic, counted apart and never billed.

Errors

StatusCodeWhat it means
400invalid_rangefrom or to is not a month, or from is after to.

GET /v1/library/coverage

Read library coverage. Per folder: how many recordings you want and how many are approved, per language; what is waiting for review; and what students asked for that was not there.

Key scope: usage

Request

curl -X GET "$LUMI_API/library/coverage" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "nodes": [{ "nodeId": "…", "path": "optics/mirrors", "title": "Mirrors", "lessons": 7, "wantedVariants": 21, "approvedVariants": 18, "languages": { "Hindi": { "wanted": 7, "approved": 6 } } }],
  "totals": { "lessons": 7, "ready": 6, "wantedVariants": 21, "approvedVariants": 18, "inReview": 3, "reviewQueueOldestAt": "2026-10-20T10:00:00.000Z" },
  "demand": [{ "lessonId": "convex-lens-images", "reason": "lesson_not_available", "refused": 14, "lastAt": "2026-10-21T07:55:00.000Z" }]
}
  • demand lists library launches refused in the last 30 days because the lesson or its recording was missing. Lessons in no folder are the last row.
  • Without page, limit or folder the answer is the whole library, exactly as above. With any of them nodes is one page (page from 1; limit 1 to 100, default 25), and the answer adds page, limit, total and hasMore; totals and demand stay the whole library's.
  • folder is a folder's nodeId or its path (an address a console move took it from still works) and keeps that folder and every folder below it, without the no-folder row.

Errors

StatusCodeWhat it means
400invalid_pagepage is not a whole number from 1.
400invalid_limitlimit is not a whole number from 1 to 100.
400invalid_folderNo folder has that nodeId or path.

GET /v1/analytics/lessons

Read lesson results. Per lesson: starts, lessons taught and completed, questions asked, check-question accuracy and ratings, with a row per recording.

Key scope: usage

Request

curl -X GET "$LUMI_API/analytics/lessons?from=2026-09&to=2026-10" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "from": "2026-09",
  "to": "2026-10",
  "lessons": [{
    "lessonId": "concave-mirror-images", "title": "Images in a concave mirror", "path": "optics/mirrors",
    "starts": 410, "taught": 388, "completes": 301, "completionRate": 0.78,
    "doubtsPer100": 42, "checkAccuracy": 0.71, "rating": { "count": 96, "mean": 4.4 },
    "versions": [{ "versionId": "ver_…", "rootVersionId": "ver_…", "variant": { "language": "Hindi", "depth": "balanced", "difficulty": "standard" }, "starts": 410, "taught": 388, "completes": 301, "checks": [ … ], "ratings": { "count": 96, "mean": 4.4, "histogram": [1, 2, 6, 31, 56] } }],
    "recordings": [{ "rootVersionId": "ver_…", "variant": { "language": "Hindi", "depth": "balanced", "difficulty": "standard" }, "versionIds": ["ver_…", "ver_…"], "starts": 410, "taught": 388, "completes": 301, "completionRate": 0.78, "rating": { "count": 96, "mean": 4.4 } }]
  }]
}
  • from and to are months (YYYY-MM, India time). from defaults to the current month, and to defaults to from.
  • Sorted by lessons taught. A version row also carries where unfinished lessons stopped (dropOff) and each check question's answers.
  • A corrected recording starts its numbers at zero under its own versionId. recordings adds each recording and every corrected version made from it together, under the first recording's id (rootVersionId); versions keeps one row per version.
  • Staff and sandbox students are left out of every number.
  • Without page, limit or folder every lesson taught in the range is listed, exactly as above. With any of them lessons is one page, still most taught first (page from 1; limit 1 to 100, default 25), and the answer adds page, limit, total and hasMore. from and to work as before.
  • folder is a folder's nodeId or its path (an address a console move took it from still works) and keeps only the lessons in that folder and every folder below it.

Errors

StatusCodeWhat it means
400invalid_rangefrom or to is not a month, or from is after to.
400invalid_pagepage is not a whole number from 1.
400invalid_limitlimit is not a whole number from 1 to 100.
400invalid_folderNo folder has that nodeId or path.

GET /v1/learners/{userId}/progress

Read a student's progress. One student's lessons: totals, per folder, what they have shown they know, and their recent lessons.

Key scope: usage

Request

curl -X GET "$LUMI_API/learners/stu_48213/progress" \
  -H "Authorization: Bearer $LUMI_KEY"

Answer · 200

{
  "userId": "stu_48213", "entitlement": "school_plan", "status": "active",
  "sessions": 22, "taught": 20, "completed": 17, "doubts": 41, "checkAccuracy": 0.74,
  "byNode": [{ "nodeId": "…", "path": "optics/mirrors", "title": "Mirrors", "lessonsDone": 5, "lessonsStarted": 6, "lessons": [ … ] }],
  "mastery": [{ "nodeId": "…", "path": "optics/mirrors", "concepts": 9, "attempts": 30, "correct": 22, "state": "shaky" }],
  "recent": [{ "sessionId": "…", "at": "2026-10-20T16:40:00.000Z", "mode": "library", "lessonId": "concave-mirror-images", "completed": true, "doubts": 2 }]
}
  • mastery is evidence, not a score: state is solid, shaky, seen or none.
  • Folders come in syllabus order, with lessons in no folder last.
  • recentLimit (1 to 100, default 20) sizes recent, newest first. folder is a folder's nodeId or its path (an address a console move took it from still works) and keeps byNode, mastery and recent to lessons in that folder and every folder below it, while sessions, taught, completed, minutes, doubts and checkAccuracy stay the student's whole. Without either the answer is exactly as above.

Errors

StatusCodeWhat it means
400invalid_user_idThe id in the address is not usable.
400pii_in_idThe id in the address looks like an email or phone number.
400invalid_limitrecentLimit is not a whole number from 1 to 100.
400invalid_folderNo folder has that nodeId or path.
404not_foundNo student has this id.
410learner_deletedThe student was erased.

Routes the player calls for you

These take no key. The player and the console's review tab call them from the browser; your server never does. They are listed so the codes make sense when you see them.

POST /v1/launch/exchange

Exchange the launch link. The player calls this from the student's browser as soon as it opens a launch link. It trades the one-time code for the lesson, the student's plan, your brand and a short sign-in for the lesson. Your server never calls it.

No key: called from the browser

What the browser sends

{ "nonce": "<the code after #launch=>" }

Answer · 200

{
  "mode": "library",
  "lesson": { "lessonId": "concave-mirror-images", "title": "Images in a concave mirror" },
  "sandbox": false,
  "entitlement": "school_plan",
  "caps": { "lessonsLeftToday": 4, "doubtsLeftToday": 20 },
  "language": "Hindi",
  "brand": { "tutorName": "…", "accent": "#…", "poweredBy": true },
  "expiresIn": 3600
}
  • Exactly once: a second exchange of the same code, or one after five minutes, is refused.
  • The answer also carries the player's sign-in for this lesson and the opening message the player sends. Nothing in it is for your server.

Errors

StatusCodeWhat it means
400invalid_nonceThe request carried no code. A code that was cut short or changed answers launch_expired instead.
410launch_expiredThe link was already used, is more than five minutes old, or its code was changed on the way. Ask your server for a new one.
403learner_suspendedThe student was paused after the link was issued.
429rate_limitedMore than 120 exchanges a minute from one network address (a large lab behind one address can reach this). Write to us if your classrooms need more.
503token_unavailableWe could not sign the student in just now. Ask for a new link and try again.

POST /v1/review/open

Open a recording for review. The review tab calls this when a console member presses Watch. It trades the one-time review link for a reviewer's copy of the recording. Nothing here counts as a lesson, a launch or usage.

No key: called from the browser

What the browser sends

{ "ticket": "rvt_…", "sitting": "rvs_…" }

Answer · 200

{
  "sittingUntil": "2026-10-21T14:30:00.000Z",
  "bundle": { "recording": { "lessonId": "concave-mirror-images", "title": "Images in a concave mirror" }, "plan": { … }, "steps": [ … ], "checks": [ … ] }
}
  • The review link must be opened within five minutes of pressing Watch; the review then lasts four hours.
  • Reloading the same tab opens the same review again and resumes at the last step watched.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review link is malformed or incomplete.
410review_link_expiredThe review link is unknown or was not opened within five minutes. Press Watch again.
409review_link_usedThe link was already opened in another tab. Press Watch again.
410review_endedThe four hours of this review are over. Press Watch again.
403review_access_endedThe member who pressed Watch no longer has access, or the organisation is closed.
404recording_unavailableThe recording or its lesson is gone.
503recording_unavailableWe could not read the recording just now. Try again.
429rate_limitedToo many reviews opened at once. Wait for Retry-After.

POST /v1/review/media

Refresh a review's audio and pictures. The review tab calls this to renew the links to a recording's audio and pictures, which last 30 minutes each.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…" }

Answer · 200

{ "media": { … }, "mediaExpiresAt": "2026-10-21T11:00:00.000Z" }
  • A line whose link could not be renewed plays silently, and a missing picture shows a placeholder.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
410review_endedThe review is over. Press Watch again.
403review_access_endedThe member no longer has access.
404recording_unavailableThe recording is gone.
503recording_unavailableWe could not read the recording just now.
429rate_limitedToo many refreshes. Wait for Retry-After.

POST /v1/review/progress

Report what a reviewer watched. The review tab reports the steps the reviewer played to the end. The console's Approve dialog shows the share as Watched N%. It is a soft signal: it is capped by time (one step per two seconds), not proof of attention.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "steps": [0, 1, 2], "at": 3 }

Answer · 200

{ "watched": 25 }
  • Steps not credited yet come back in uncredited, and the tab sends them again later.

Errors

StatusCodeWhat it means
400invalid_progresssteps or at is not a whole number in range.
400invalid_review_linkThe review's sitting is malformed.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
503recording_unavailableWe could not save the report just now; the tab keeps it and sends it again.
429rate_limitedToo many reports. Wait for Retry-After.

POST /v1/review/material

Open the material a recording cites. The review tab calls this when a reviewer opens one of your PDFs, notes or video links that a step cites. A PDF link lasts five minutes. A student's own files are never returned here.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "ref": "m1" }

Answer · 200

{ "kind": "pdf", "title": "Chapter 4 notes", "url": "https://…", "expiresAt": "2026-10-21T10:35:00.000Z" }
  • kind is pdf (a link), text (your pasted notes, as text) or youtube (the video link).

Errors

StatusCodeWhat it means
404material_unavailableThe recording does not cite this material, or it was deleted.
400invalid_review_linkThe review's sitting is malformed.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
503recording_unavailableWe could not read the recording just now.
429rate_limitedToo many opens. Wait for Retry-After.

POST /v1/review/findings/decide

Decide a recording check's finding. The review tab calls this when a reviewer applies, dismisses or reopens one of the automatic checker's findings about a recording. Applying a fix only sets it aside for a corrected recording: nothing in the recording changes, and nothing is charged. Only reviewers, admins and owners can decide; every decision reaches Activity.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "findingId": "fnd_…", "decision": "apply", "note": "The textbook agrees" }

Answer · 200

{ "finding": { "findingId": "fnd_…", "severity": "major", "state": "applied", "decision": { "by": "faculty@school.example", "at": "2026-10-22T10:05:00.000Z" } }, "qa": { "state": "done", "counts": { "critical": 0, "major": 2, "minor": 1 }, "open": 2 }, "patch": { "rev": 1, "ops": 1 } }
  • decision is apply, dismiss or reopen. An apply may carry an edited fix in op; then the decision says editedFix.
  • The first decision wins: a second one on the same finding answers finding_decided with what the first left and who made it.
  • Shown only while recording checks are on for your organisation.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
400invalid_decisionThe decision or the finding id is not one the tab can send.
400invalid_noteThe note is too long.
400pii_in_reasonThe note carries an email address or a phone number.
400fix_needs_wordsThis fix needs the reviewer's own words: send an edited fix.
400no_fix_to_applyThe finding has no change to apply.
400fix_address_mismatchAn edited fix must stay on the finding's step.
400invalid_opThe edited fix is not a change the editor makes.
400op_text_too_longThe new words are longer than the step allows.
400op_text_requiredThe edited fix has no words.
400op_options_invalidA check needs two to six different options.
400op_answer_not_an_optionThe answer is not one of the check's options.
400op_address_missingThat part of the step is not in the recording.
400op_wrong_eventThe change does not fit that part of the step.
400op_no_specThat drawing cannot be edited.
400op_last_beatA topic keeps at least one step.
400op_beat_has_dependentsOther steps build on this one.
400question_beat_no_pictureA check cannot have a picture added.
400op_picture_limitThe step holds as many pictures as it can.
400op_spec_unrenderableThe edited drawing cannot be drawn.
400op_script_mismatchA new line must be in the same script as the line it replaces.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
403review_decide_forbiddenThe member who pressed Watch cannot decide findings (for example, an analyst).
404findings_unavailableRecording checks are not shown for your organisation.
404finding_not_foundThe finding is not this recording's latest check.
404recording_unavailableThe recording is gone.
409finding_decidedSomeone decided it first; the answer says what they left.
409version_retiredThe recording was taken off.
409beat_droppedA change already set aside takes the step out.
409patch_conflictOthers were changing the recording at the same moment. Try again.
429rate_limitedToo many decisions. Wait for Retry-After.
503recording_unavailableWe could not save the decision just now.

POST /v1/review/findings/apply-all

Apply every sure fix. The review tab's Apply all: every open finding the checker is sure of, whose fix it can write, is applied and set aside for a corrected recording in one step. The rest stay for a person, each with why. Nothing in the recording changes and nothing is charged.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "note": "Checked against the textbook" }

Answer · 200

{ "applied": [{ "findingId": "fnd_…", "state": "applied" }], "skipped": [{ "findingId": "fnd_…", "ref": "SAY 0115", "title": "…", "why": "needs_words" }], "qa": { "state": "done", "counts": { "critical": 0, "major": 2, "minor": 1 }, "open": 1 }, "patch": { "rev": 2, "ops": 2 } }
  • why is medium_confidence (the checker is less sure), needs_words (the fix needs the reviewer's own words), no_fix, conflict (another fix already takes that place), finding_decided, or the editor's refusal of the fix.
  • Shown only while recording checks are on for your organisation.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
400invalid_noteThe note is too long.
400pii_in_reasonThe note carries an email address or a phone number.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
403review_decide_forbiddenThe member who pressed Watch cannot change the recording (for example, an analyst).
404recording_unavailableThe recording is gone.
409version_retiredThe recording was taken off.
429rate_limitedToo many changes. Wait for Retry-After.
503recording_unavailableWe could not save the change just now.
404findings_unavailableRecording checks are not shown for your organisation.
409patch_conflictOthers were changing the recording at the same moment. Try again.

POST /v1/review/pictures

List your own pictures for a fix. The review tab lists your organisation's own pictures, so a reviewer can put one in place of a recording's picture. Newest first, at most 60, each with a link that works for a short time.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…" }

Answer · 200

{ "pictures": [{ "materialId": "mat_…", "title": "Heart diagram", "url": "https://…", "expiresAt": "2026-10-23T11:00:00.000Z" }] }
  • An empty list, never a refusal, when the member cannot change recordings, recording checks are off, or your organisation's material is off. It changes nothing.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
429rate_limitedToo many requests. Wait for Retry-After.
503recording_unavailableWe could not read the pictures just now.

POST /v1/review/patch/stage

Edit a step by hand. The review tab's Edit this beat: a reviewer's own change to any line, board item, picture, drawing or check, set aside beside the applied fixes for a corrected recording. Nothing in the recording changes and nothing is charged until someone makes the corrected recording. Only reviewers, admins and owners can edit; every change reaches Activity, saying what kind of change and where, never the words.

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "op": { "action": "revoice", "segId": "s3", "index": 0, "text": "The ego keeps the peace." }, "note": "Plainer words" }

Answer · 200

{ "patch": { "rev": 4, "changes": [{ "address": "s3:0", "op": { "action": "revoice", "segId": "s3", "index": 0, "text": "The ego keeps the peace." }, "words": "Say instead: "The ego keeps the peace."", "from": "hand", "by": "faculty@school.example", "at": "2026-10-23T10:05:00.000Z" }] }, "reopened": [], "qa": { "state": "done", "counts": { "critical": 0, "major": 1, "minor": 0 }, "open": 1 } }
  • op is one of the editor's changes, the same as an edited fix on a finding. One change per place: a second change there replaces the first.
  • A hand edit at a place an applied fix holds replaces that fix, and its finding goes back to open; it is in reopened.
  • patch_conflict means another reviewer changed the set-aside changes at the same moment: the answer carries them as they now stand, so the reviewer can look and try again.
  • Shown only while the step editor is on for your organisation.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
400invalid_noteThe note is too long.
400pii_in_reasonThe note carries an email address or a phone number.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
403review_decide_forbiddenThe member who pressed Watch cannot change the recording (for example, an analyst).
404recording_unavailableThe recording is gone.
409version_retiredThe recording was taken off.
429rate_limitedToo many changes. Wait for Retry-After.
503recording_unavailableWe could not save the change just now.
400invalid_opThe change is not one the editor makes.
400op_text_too_longThe new words are longer than the step allows.
400op_text_requiredThe change has no words.
400op_options_invalidA check needs two to six different options.
400op_answer_not_an_optionThe answer is not one of the check's options.
400op_address_missingThat part of the step is not in the recording.
400op_wrong_eventThe change does not fit that part of the step.
400op_no_specThat drawing cannot be edited.
400op_last_beatA topic keeps at least one step.
400op_beat_has_dependentsOther steps build on this one.
400question_beat_no_pictureA check cannot have a picture added.
400op_picture_limitThe step holds as many pictures as it can.
400op_spec_unrenderableThe edited drawing cannot be drawn.
400op_script_mismatchA new line must be in the same script as the line it replaces.
400op_no_promptThis picture has no caption to draw it again from: give new words.
403material_not_enabledYour own pictures cannot be used: material is off for your organisation.
400material_unknownThat picture is not one of your organisation's.
400material_not_readyThat picture is still being prepared.
400material_not_a_pictureThat material is not a picture.
400material_too_largeThat picture is too large.
404editing_unavailableThe step editor is not on for your organisation.
409beat_droppedA change already set aside takes the step out.
409patch_conflictAnother reviewer changed the set-aside changes at the same moment; the answer carries them. Try again.

POST /v1/review/patch/unstage

Remove a set-aside change. The review tab's Remove: one change set aside for a corrected recording is taken back, whether it was a hand edit or a finding's fix (that finding goes back to open).

No key: called from the browser

What the browser sends

{ "sitting": "rvs_…", "address": "s3:0" }

Answer · 200

{ "patch": { "rev": 5, "changes": [] }, "reopened": [], "qa": { "state": "done", "counts": { "critical": 0, "major": 1, "minor": 0 }, "open": 1 } }
  • address is the change's own key, as the set-aside list gives it.

Errors

StatusCodeWhat it means
400invalid_review_linkThe review's sitting is malformed.
400invalid_noteThe note is too long.
400pii_in_reasonThe note carries an email address or a phone number.
410review_endedThe review is over.
403review_access_endedThe member no longer has access.
403review_decide_forbiddenThe member who pressed Watch cannot change the recording (for example, an analyst).
404recording_unavailableThe recording is gone.
409version_retiredThe recording was taken off.
429rate_limitedToo many changes. Wait for Retry-After.
503recording_unavailableWe could not save the change just now.
404editing_unavailableThe step editor is not on for your organisation.
400invalid_addressThe address is not one the list gives.
404change_not_foundNothing is set aside at that place.
409patch_conflictAnother reviewer changed the set-aside changes at the same moment; the answer carries them. Try again.
Something missing?

If a route answers a code this page does not list, write to support@sketchmind.ai with the route and the code. We keep this page in step with the API.