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
| Environment | API address | Keys |
|---|---|---|
| Sandbox (testing) | https://staging.sketchmind.ai/v1 | sk_sandbox_… |
| Live (your real students) | https://platform.sketchmind.ai/v1 | sk_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 pageKeys 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.
| Scope | What it allows |
|---|---|
| launch | Open lessons: ask for a launch link for a student. |
| learners | Manage students: read a student, change their plan, pause or erase them. |
| library | Manage the library: import lessons and read what is ready. |
| usage | Read 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_limitedwith aRetry-Afterheader and the same number inretryAfterandretryAfterSeconds. - 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
| Status | Code | What it means |
|---|---|---|
| 401 | invalid_api_key | The key is missing, mistyped or unknown. |
| 401 | api_key_revoked | The key was turned off, or it was replaced and its 24 hours of grace are over. Use the new key. |
| 403 | sandbox_key_not_accepted | A sandbox key was sent to the live address. Sandbox keys work only on the sandbox address. |
| 403 | org_suspended | Your organisation is suspended. Write to us. |
| 403 | insufficient_scope | The key cannot do this. The answer's scope field names the scope it needs. |
| 429 | rate_limited | More than 120 requests a minute with this key. Wait for the seconds in Retry-After (also retryAfter and retryAfterSeconds in the body). |
| 503 | partner_auth_unavailable | We could not check the key just now. Try again. |
From reading the request
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. |
| 413 | body_too_large | The body is over 1 MB. |
| 415 | unsupported_media_type | The body uses an encoding or character set we cannot read. Send plain UTF-8 JSON. |
| 4xx | bad_request | The body could not be read, for example it was cut off part-way. |
| 404 | not_found | No route answers this path and method. |
| 500 | internal_error | Something 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_body | The body is not a JSON object. |
| 400 | invalid_user_id | userId is missing or not a usable id: 1 to 128 letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit. |
| 400 | pii_in_id | userId looks like an email or phone number. Send your own opaque id. |
| 400 | pii_not_accepted | The body carries personal data (a name, phone, email, date of birth, address or image). The field is named in the answer. |
| 400 | invalid_mode | mode is not library or ask. The answer lists the allowed words. |
| 400 | invalid_lesson_id | A library launch without a lessonId. |
| 400 | invalid_valid_till | validTill is not a date. |
| 400 | invalid_delivery | context.delivery is not anchored, lean or direct. The answer lists the allowed words. |
| 400 | language_unsupported | No language answers to context.language here. The answer lists the supported ones. |
| 403 | unknown_entitlement | The plan you named is not one of your plans. |
| 403 | language_not_entitled | The student's plan does not include the language this lesson would teach in. The answer lists the allowed ones. |
| 403 | learner_suspended | The student is paused, or was erased in the last 90 days. |
| 403 | mode_not_allowed | The student's plan does not allow this mode (library or ask). |
| 403 | trial_exhausted | The student has used every lesson of their trial. |
| 403 | lessons_per_day | The student has used today's lessons. Counts start again at midnight, India time. |
| 403 | lessons_paused | Your organisation's monthly limit is reached, so new lessons are paused. Lessons already running finish. |
| 403 | org_suspended | Your organisation is suspended or closed. |
| 403 | variant_not_available | The lesson has approved recordings, but none in this language, depth, difficulty or delivery, and the lesson does not fall back to the nearest one. |
| 404 | lesson_not_available | The Lesson ID is unknown, hidden, retired, or has nothing approved yet. |
| 409 | org_policy_missing | Your organisation has no plans yet. We set the first ones up with you. |
| 429 | rate_limited | This student was launched 6 times in the last minute. Wait for Retry-After. |
| 503 | learner_unavailable | We could not set up the student just now. Try again. |
| 503 | launch_unavailable | We 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_user_id | The id in the address is not usable. |
| 400 | pii_in_id | The id in the address looks like an email or phone number. |
| 404 | not_found | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_user_id | The id in the address is not usable. |
| 400 | pii_in_id | The id in the address looks like an email or phone number. |
| 400 | invalid_body | The body is not a JSON object. |
| 400 | pii_not_accepted | The body carries personal data. The field is named in the answer. |
| 400 | unsupported_field | The body has a field this route does not change. The field is named in the answer. |
| 400 | unknown_entitlement | The plan is not one of your plans. |
| 400 | invalid_attributes | attributes is not an object of the four allowed keys. |
| 400 | invalid_valid_till | validTill is not a date or null. |
| 400 | invalid_status | status is not active or suspended. |
| 404 | not_found | No student has this id. |
| 410 | learner_deleted | The 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_user_id | The id in the address is not usable. |
| 400 | pii_in_id | The id in the address looks like an email or phone number. |
| 404 | not_found | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_page | page is not a whole number from 1. |
| 400 | invalid_limit | limit is not a whole number from 1 to 100. |
| 400 | invalid_q | q was sent more than once. |
| 400 | invalid_status | status is not one of draft, generating, partial, ready, retired or hidden. |
| 400 | invalid_folder | No folder has that nodeId or path. |
| 400 | invalid_versions | versions 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
| Status | Code | What it means |
|---|---|---|
| 404 | not_found | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_csv | The 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. |
| 400 | invalid_body | The body is not JSON with a csv text field. |
| 400 | expect_required | A confirm must send the check's expect counts. Run the check and send its expect back. |
| 400 | invalid_expect | expect is not five whole numbers of zero or more. |
| 409 | plan_changed | The 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. |
| 409 | library_busy | Someone else is changing the library right now (busy says who: upload, change or sketchmind). Try again after Retry-After. |
| 409 | import_interrupted | The upload stopped part-way. The rows applied stay (rowsApplied, jobsQueued); run the check again to see what is left. |
| 409 | recordings_paused | New recordings are paused for your organisation this month. Write to us. |
| 413 | csv_too_large | The file is too large. Split it into smaller files. |
| 500 | import_failed | The 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
| Status | Code | What it means |
|---|---|---|
| 404 | not_found | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_range | from 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_page | page is not a whole number from 1. |
| 400 | invalid_limit | limit is not a whole number from 1 to 100. |
| 400 | invalid_folder | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_range | from or to is not a month, or from is after to. |
| 400 | invalid_page | page is not a whole number from 1. |
| 400 | invalid_limit | limit is not a whole number from 1 to 100. |
| 400 | invalid_folder | No 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_user_id | The id in the address is not usable. |
| 400 | pii_in_id | The id in the address looks like an email or phone number. |
| 400 | invalid_limit | recentLimit is not a whole number from 1 to 100. |
| 400 | invalid_folder | No folder has that nodeId or path. |
| 404 | not_found | No student has this id. |
| 410 | learner_deleted | The 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_nonce | The request carried no code. A code that was cut short or changed answers launch_expired instead. |
| 410 | launch_expired | The 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. |
| 403 | learner_suspended | The student was paused after the link was issued. |
| 429 | rate_limited | More 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. |
| 503 | token_unavailable | We 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review link is malformed or incomplete. |
| 410 | review_link_expired | The review link is unknown or was not opened within five minutes. Press Watch again. |
| 409 | review_link_used | The link was already opened in another tab. Press Watch again. |
| 410 | review_ended | The four hours of this review are over. Press Watch again. |
| 403 | review_access_ended | The member who pressed Watch no longer has access, or the organisation is closed. |
| 404 | recording_unavailable | The recording or its lesson is gone. |
| 503 | recording_unavailable | We could not read the recording just now. Try again. |
| 429 | rate_limited | Too 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 410 | review_ended | The review is over. Press Watch again. |
| 403 | review_access_ended | The member no longer has access. |
| 404 | recording_unavailable | The recording is gone. |
| 503 | recording_unavailable | We could not read the recording just now. |
| 429 | rate_limited | Too 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_progress | steps or at is not a whole number in range. |
| 400 | invalid_review_link | The review's sitting is malformed. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 503 | recording_unavailable | We could not save the report just now; the tab keeps it and sends it again. |
| 429 | rate_limited | Too 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
| Status | Code | What it means |
|---|---|---|
| 404 | material_unavailable | The recording does not cite this material, or it was deleted. |
| 400 | invalid_review_link | The review's sitting is malformed. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 503 | recording_unavailable | We could not read the recording just now. |
| 429 | rate_limited | Too 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 400 | invalid_decision | The decision or the finding id is not one the tab can send. |
| 400 | invalid_note | The note is too long. |
| 400 | pii_in_reason | The note carries an email address or a phone number. |
| 400 | fix_needs_words | This fix needs the reviewer's own words: send an edited fix. |
| 400 | no_fix_to_apply | The finding has no change to apply. |
| 400 | fix_address_mismatch | An edited fix must stay on the finding's step. |
| 400 | invalid_op | The edited fix is not a change the editor makes. |
| 400 | op_text_too_long | The new words are longer than the step allows. |
| 400 | op_text_required | The edited fix has no words. |
| 400 | op_options_invalid | A check needs two to six different options. |
| 400 | op_answer_not_an_option | The answer is not one of the check's options. |
| 400 | op_address_missing | That part of the step is not in the recording. |
| 400 | op_wrong_event | The change does not fit that part of the step. |
| 400 | op_no_spec | That drawing cannot be edited. |
| 400 | op_last_beat | A topic keeps at least one step. |
| 400 | op_beat_has_dependents | Other steps build on this one. |
| 400 | question_beat_no_picture | A check cannot have a picture added. |
| 400 | op_picture_limit | The step holds as many pictures as it can. |
| 400 | op_spec_unrenderable | The edited drawing cannot be drawn. |
| 400 | op_script_mismatch | A new line must be in the same script as the line it replaces. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 403 | review_decide_forbidden | The member who pressed Watch cannot decide findings (for example, an analyst). |
| 404 | findings_unavailable | Recording checks are not shown for your organisation. |
| 404 | finding_not_found | The finding is not this recording's latest check. |
| 404 | recording_unavailable | The recording is gone. |
| 409 | finding_decided | Someone decided it first; the answer says what they left. |
| 409 | version_retired | The recording was taken off. |
| 409 | beat_dropped | A change already set aside takes the step out. |
| 409 | patch_conflict | Others were changing the recording at the same moment. Try again. |
| 429 | rate_limited | Too many decisions. Wait for Retry-After. |
| 503 | recording_unavailable | We 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 400 | invalid_note | The note is too long. |
| 400 | pii_in_reason | The note carries an email address or a phone number. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 403 | review_decide_forbidden | The member who pressed Watch cannot change the recording (for example, an analyst). |
| 404 | recording_unavailable | The recording is gone. |
| 409 | version_retired | The recording was taken off. |
| 429 | rate_limited | Too many changes. Wait for Retry-After. |
| 503 | recording_unavailable | We could not save the change just now. |
| 404 | findings_unavailable | Recording checks are not shown for your organisation. |
| 409 | patch_conflict | Others 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 429 | rate_limited | Too many requests. Wait for Retry-After. |
| 503 | recording_unavailable | We 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 400 | invalid_note | The note is too long. |
| 400 | pii_in_reason | The note carries an email address or a phone number. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 403 | review_decide_forbidden | The member who pressed Watch cannot change the recording (for example, an analyst). |
| 404 | recording_unavailable | The recording is gone. |
| 409 | version_retired | The recording was taken off. |
| 429 | rate_limited | Too many changes. Wait for Retry-After. |
| 503 | recording_unavailable | We could not save the change just now. |
| 400 | invalid_op | The change is not one the editor makes. |
| 400 | op_text_too_long | The new words are longer than the step allows. |
| 400 | op_text_required | The change has no words. |
| 400 | op_options_invalid | A check needs two to six different options. |
| 400 | op_answer_not_an_option | The answer is not one of the check's options. |
| 400 | op_address_missing | That part of the step is not in the recording. |
| 400 | op_wrong_event | The change does not fit that part of the step. |
| 400 | op_no_spec | That drawing cannot be edited. |
| 400 | op_last_beat | A topic keeps at least one step. |
| 400 | op_beat_has_dependents | Other steps build on this one. |
| 400 | question_beat_no_picture | A check cannot have a picture added. |
| 400 | op_picture_limit | The step holds as many pictures as it can. |
| 400 | op_spec_unrenderable | The edited drawing cannot be drawn. |
| 400 | op_script_mismatch | A new line must be in the same script as the line it replaces. |
| 400 | op_no_prompt | This picture has no caption to draw it again from: give new words. |
| 403 | material_not_enabled | Your own pictures cannot be used: material is off for your organisation. |
| 400 | material_unknown | That picture is not one of your organisation's. |
| 400 | material_not_ready | That picture is still being prepared. |
| 400 | material_not_a_picture | That material is not a picture. |
| 400 | material_too_large | That picture is too large. |
| 404 | editing_unavailable | The step editor is not on for your organisation. |
| 409 | beat_dropped | A change already set aside takes the step out. |
| 409 | patch_conflict | Another 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
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_review_link | The review's sitting is malformed. |
| 400 | invalid_note | The note is too long. |
| 400 | pii_in_reason | The note carries an email address or a phone number. |
| 410 | review_ended | The review is over. |
| 403 | review_access_ended | The member no longer has access. |
| 403 | review_decide_forbidden | The member who pressed Watch cannot change the recording (for example, an analyst). |
| 404 | recording_unavailable | The recording is gone. |
| 409 | version_retired | The recording was taken off. |
| 429 | rate_limited | Too many changes. Wait for Retry-After. |
| 503 | recording_unavailable | We could not save the change just now. |
| 404 | editing_unavailable | The step editor is not on for your organisation. |
| 400 | invalid_address | The address is not one the list gives. |
| 404 | change_not_found | Nothing is set aside at that place. |
| 409 | patch_conflict | Another reviewer changed the set-aside changes at the same moment; the answer carries them. Try again. |
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.