Client
lessons.list()
Fetches available lessons from the courses configured in timeback.config.json.
Filter to a specific configured course. If omitted, returns lessons across all configured courses.
Return type
Examples
lessons.start()
Starts or resumes a lesson session. Returns a LessonSession that manages the question loop and time tracking. An activity tracker starts automatically, so TimeSpentEvent heartbeats begin immediately.
The lesson to start.
Course reference for time tracking. Must match a course in
timeback.config.json. Use either subject + grade or a course code.Determines how the SDK handles the question loop and completion. Pass
lesson.type from the discovery result. The two primary types behave differently:powerpath-100: adaptive (questions served one at a time, difficulty adjusts, session completes when score reaches 100)quiz: static (all questions fetched in a batch, session completes via explicit finalization)
test-out, placement, unit-test) follow the same static pattern as quiz.Display name for the activity tracker. Defaults to the lesson name.
Start a fresh attempt instead of resuming an existing one. Without this,
lessons.start() resumes the student’s current in-progress attempt.When true, the behavior depends on the lesson type:- Quiz-like types (
quiz,test-out, etc.): the current attempt is finalized first (scored with whatever was answered), then a new attempt is created powerpath-100: PowerPath attempts cannot be finalized via the API, so a new attempt is created directly
Examples
Lesson session
The object returned bylessons.start(). Manages the question loop, scoring state, and time tracking for a single lesson attempt.
Properties
Most properties are set once when the session is created.
score and finalized are
exceptions: they update live as the student progresses.The lesson identifier passed to
lessons.start().The delivery mode for this session. Resolved from the server response, falling back to the
lessonType you passed to lessons.start(), then to 'quiz'.Controls how the SDK fetches questions (next() hits the server each time for adaptive, fetches all at once for linear) and how completion works (adaptive auto-completes at score 100, linear requires explicit finalization).The PowerPath attempt number (1, 2, 3, …).
undefined on first-ever access when no prior
attempt data exists.Cumulative score for the current attempt. Starts at the value returned by PowerPath (0 for new attempts, or the saved score when resuming).Updates live after each
submit() call and again after complete() with the final score. For powerpath-100, this is a 0–100 mastery scale where reaching 100 means the lesson auto-completes. For quiz types, the score typically updates at finalization.Total questions in the lesson, as reported by PowerPath. For linear lessons (
quiz, test-out,
etc.), this is the fixed question count. For adaptive lessons (powerpath-100), this may be
undefined since the total varies based on the student’s performance.Number of questions the student had already seen when the session started. For
powerpath-100,
reflects how many questions were served before the session was resumed. For linear lesson types,
always 0 (linear quizzes track answered questions differently via their local buffer).Whether the lesson attempt has been finalized. When
true, scores are locked and the gradebook is updated.Initial value depends on lesson type: for powerpath-100, always starts false (adaptive sessions are never pre-finalized). For quiz types, reflects whether the attempt was already completed when resuming.Updates live: set to true by submit() when the server signals completion (e.g., powerpath-100 reaching score 100), and by complete() with the server’s finalization result.Methods
Returns the next question, or
null when there are no more questions.Behavior depends on lesson type:powerpath-100(adaptive): each call makes a server round-trip. PowerPath selects the next question based on the student’s performance so far. Returnsnullwhen PowerPath signals completion (score reached 100).quizand other linear types: the first call fetches all questions from the server in a single batch and buffers them locally. Subsequent calls return the next unanswered question from the buffer with no network request. Already-answered questions (from a resumed attempt) are skipped automatically.
null immediately if the session is already completed.Submits the student’s answer to PowerPath and returns the scored result.After each call,
session.score is updated with the server’s response. If the server signals that the lesson is complete (e.g., powerpath-100 reaching score 100), session.finalized is set to true and subsequent next() calls return null.For powerpath-100, correct reflects real-time scoring (the server evaluates immediately). For quiz types, correct is always false during the quiz. Evaluation happens at finalization.Finalizes the lesson in two steps:
- Server: calls PowerPath’s finalization endpoint to lock in the score, calculate accuracy, and trigger gradebook writes. For quiz types, this is where scoring actually happens. For
powerpath-100, the score is already computed; this step confirms it. - Client: calls
activity.end()to flush the final time tracking heartbeat. If the flush fails, the result still contains valid scoring data.timeTrackingSentwill befalseanderrorwill describe what went wrong.
session.score and session.finalized with the server’s final values.pause()
Flushes any accumulated time to the server, then stops heartbeats until
resume() is called.
No-op if already paused or if the session has ended. Paused time is not counted as active
learning time.resume()
Starts a fresh time tracking window and restarts heartbeats. No-op if not currently paused or if
the session has ended.
LessonQuestion
The object returned by session.next():
content.rawXml field contains QTI XML. Your app is responsible for parsing and rendering this.
LessonSubmitResult
The object returned by session.submit():
LessonSessionCompleteResult
The object returned by session.complete():
timeTrackingSent can be false even when the lesson completed successfully. The scoring data
is always reliable; only the last ~15s of time data may be missing. See Handle time tracking
errors.lessons.attempts()
Lists all attempts for a lesson.
The lesson to list attempts for.
Return type
lessons.attemptDetails()
Gets per-question data for a specific attempt. The response is a discriminated union based on lesson type.
The lesson to review. Same
id from the discovery result or the session’s lessonId.Which attempt to review (1, 2, 3, …). Get available attempt numbers from
lessons.attempts().Return type
Adaptive lessons (powerpath-100):
quiz, test-out, etc.):
LessonAttemptQuestion
getLessonAttemptQuestions()
Helper that normalizes the discriminated attemptDetails() response into a flat LessonAttemptQuestion[]:
Server
The server-side lessons namespace exposes the same operations without session management or automatic time tracking. Each operation is a standalone async function call — your backend controls the lifecycle directly. See the FastAPI or Next.js adapter docs for server setup.The server namespace uses
lesson and student identifiers directly, unlike the client API which uses lessonId and resolves the student from the authenticated session.timeback.lessons.list(input?)
Lists lessons from the configured courses. Same behavior as the client lessons.list().
Filter to a specific configured course. Accepts
{ subject, grade } or { code }. If omitted, returns lessons across all configured courses.Examples
timeback.lessons.start(input)
Starts or resumes a lesson attempt. Unlike the client’s lessons.start(), this returns a plain result object — no LessonSession or time tracking.
The lesson identifier (from
lessons.list()).The student’s Timeback ID.
Start a fresh attempt instead of resuming. Behaves the same as the client
forceNew option.Return type
Examples
timeback.lessons.next(input)
Returns the next question(s) for a lesson attempt. The return type depends on lesson type:
powerpath-100: returns a singleLessonQuestion- All other types: returns a
LessonQuestionBatchwith all questions
The lesson identifier.
The student’s Timeback ID.
Pass
"powerpath-100" for adaptive single-question delivery. Omit for batch delivery.Return type
Examples
timeback.lessons.submit(input)
Submits a student’s answer to a lesson question.
The lesson identifier.
The student’s Timeback ID.
The question ID being answered (from
LessonQuestion.id).The student’s selected answer.
Return type
Examples
timeback.lessons.complete(input)
Finalizes a lesson attempt — locks in the score and triggers gradebook writes. Unlike the client’s session.complete(), this does not flush time tracking.
The lesson identifier.
The student’s Timeback ID.
Return type
Examples
timeback.lessons.attempts(input)
Lists all attempts for a lesson/student pair. Same return type as the client lessons.attempts().
The lesson identifier.
The student’s Timeback ID.
Examples
timeback.lessons.attemptDetails(input)
Returns raw progress data for a specific attempt. See client lessons.attemptDetails() for the discriminated return shape.
The lesson identifier.
The student’s Timeback ID.
Which attempt to review (1, 2, 3, …).