Reference - Timeback Docs (Beta)

Client

`lessons.list()`

Fetches available lessons from the courses configured in timeback.config.json.

ActivityCourseRef

Filter to a specific configured course. If omitted, returns lessons across all configured courses.

Show subject + grade selector

TimebackSubject

required

Course subject (e.g. "Math", "Reading").

TimebackGrade

required

Grade level (e.g. 5).

Show course code selector

string

required

Unique course code (e.g. "CS-101"). Use for grade-less apps.

Return type

Response shape (not executable)

{
    id: string // Unique lesson identifier
    name: string // Display name
    type: LessonType // 'powerpath-100' | 'quiz' | 'test-out' | ...
    courseId: string // Parent course ID
    questionCount?: number // May be absent
    metadata?: Record<string, unknown> // Additional lesson metadata
}

Examples

const lessons = await timeback.lessons.list()

const mathLessons = await timeback.lessons.list({
    course: { subject: 'Math', grade: 5 },
})

const lessons = await timeback.lessons.list({
    course: { code: 'CS-101' },
})

`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.

string

required

The lesson to start.

ActivityCourseRef

Course reference for time tracking. Required unless a client-level defaultCourse is configured. Must match a course in timeback.config.json. Use either subject + grade or a course code.

Show subject + grade selector

TimebackSubject

required

Course subject (e.g. "Math", "Reading").

TimebackGrade

required

Grade level (e.g. 5).

Show course code selector

string

required

Unique course code (e.g. "CS-101"). Use for grade-less apps.

LessonType

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)

Other quiz-like types (test-out, placement, unit-test) follow the same static pattern as quiz.

string

Display name for the activity tracker. Defaults to the server lesson type, then the lesson ID; pass name: lesson.name for the discovery title.

boolean

default:"false"

Request a fresh attempt instead of reusing progress. The SDK catches errors from finalization/creation; inspect the returned attempt because this option does not guarantee that a new attempt was created. Without it, existing progress can include an already finalized 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

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    lessonType: lesson.type,
    course: { subject: 'Math', grade: 5 },
})

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    lessonType: lesson.type,
    course: { subject: 'Math', grade: 5 },
    name: lesson.name,
    forceNew: true,
})

const session = await timeback.lessons.start({
    lessonId: lesson.id,
    lessonType: lesson.type,
    course: { code: 'CS-101' },
})

Lesson session

The object returned by lessons.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 updates after submit() and complete(); finalized updates only after complete(). These mutations do not automatically trigger framework rendering.

string

The lesson identifier passed to lessons.start().

LessonType

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).

number | undefined

The PowerPath attempt number (1, 2, 3, …). undefined on first-ever access when no prior attempt data exists.

number

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.

number | undefined

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

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).

boolean

Whether the lesson attempt has been finalized. This is the SDK/PowerPath progress flag, not an acknowledgement of all downstream gradebook or event delivery.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.submit() updates the private question-loop completion state, not this public flag. complete() updates the flag from the server result.

Methods

Promise<LessonQuestion | null>

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. Returns null when PowerPath signals completion (score reached 100).
quiz and 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.

Returns null immediately if the session is already completed.

Promise<LessonSubmitResult>

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), the private question-loop completion state is set and subsequent next() calls return null; public session.finalized is unchanged until complete().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.

Show parameters

string

required

The question ID being answered (from LessonQuestion.id).

string

required

The student’s selected answer.

Promise<LessonSessionCompleteResult>

Finalizes the lesson in two steps:

Server: reads progress and, for unfinalized linear lessons, attempts finalization then re-reads progress. Errors in that finalization call are caught; the result can still have finalized: false. For adaptive lessons the SDK returns current progress with finalized: true without checking a mastery threshold.
Client: calls activity.end() to flush the final time tracking heartbeat. If end() rejects, timeTrackingSent is false. Heartbeat network failures are usually swallowed inside the tracker, so true does not confirm server delivery.

Updates session.score and session.finalized with the server’s final values.

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.

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():

Response shape (not executable)

{
    id: string             // Unique question identifier
    title?: string         // Optional display title
    difficulty?: string    // Optional difficulty level
    content?: {
        rawXml?: string     // QTI XML content for rendering
    }
}

The content.rawXml field contains QTI XML. Your app is responsible for parsing and rendering this.

Your app supplies a renderer for supported interactions. The session submission API sends a single string in responses.RESPONSE; confirm that this matches your item before using this wrapper.

`LessonSubmitResult`

The object returned by session.submit():

Response shape (not executable)

{
    correct: boolean // Whether the answer was correct
    score: number // Updated cumulative score
    complete: boolean // Whether the lesson is now complete
}

`LessonSessionCompleteResult`

The object returned by session.complete():

Response shape (not executable)

{
    score: number              // Final score
    totalQuestions?: number    // May be absent
    correctQuestions?: number  // May be absent
    accuracy?: number          // May be absent
    finalized: boolean         // Whether PowerPath finalized the attempt
    lessonType: LessonType     // The lesson type
    timeSpentSeconds: number   // Active learning time
    timeTrackingSent: boolean  // Whether tracker cleanup resolved
    error?: string             // Error message if time flush failed
}

timeTrackingSent reports whether tracker cleanup threw. It is not delivery confirmation. Inspect finalized separately and reconcile missing analytics; data loss is not limited to the last heartbeat interval. See Handle time tracking errors.

`lessons.attempts()`

Lists all attempts for a lesson.

string

required

The lesson to list attempts for.

Return type

Response shape (not executable)

{
    attempt?: number
    score: number
    startedAt?: string
    completedAt?: string
    scoreStatus?: string
}

`lessons.attemptDetails()`

Gets per-question data for a specific attempt. The response is a discriminated union based on lesson type.

string

required

The lesson to review. Same id from the discovery result or the session’s lessonId.

number

required

Which attempt to review (1, 2, 3, …). Get available attempt numbers from lessons.attempts().

Return type

Adaptive lessons (powerpath-100):

Response shape (not executable)

{
    lessonType: 'powerpath-100'
    seenQuestions: LessonAttemptQuestion[]
    score: number
    totalQuestions: number
    correctQuestions: number
}

Linear lessons (quiz, test-out, etc.):

Response shape (not executable)

{
    lessonType: 'quiz' | 'test-out' | 'placement' | 'unit-test'
    questions: LessonAttemptQuestion[]
    score: number
    totalQuestions: number
    correctQuestions: number
}

`LessonAttemptQuestion`

Response shape (not executable)

{
    id: string // Question identifier
    correct?: boolean // May be absent
    response?: string | string[]
    responses?: Record<string, string | string[]>
    content?: {
        rawXml?: string // QTI XML for re-rendering
    }
}

`getLessonAttemptQuestions()`

Helper that normalizes the discriminated attemptDetails() response into a flat LessonAttemptQuestion[]:

import { getLessonAttemptQuestions } from '@timeback/sdk/client'

const details = await timeback.lessons.attemptDetails({
    lessonId: lesson.id,
    attempt: 1,
})

const questions = getLessonAttemptQuestions(details)
// Always returns LessonAttemptQuestion[] regardless of lesson type

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().

ActivityCourseRef

Filter to a specific configured course. Accepts { subject, grade } or { code }. If omitted, returns lessons across all configured courses.

Examples

const lessons = await timeback.lessons.list()
const mathLessons = await timeback.lessons.list({ course: { subject: 'Math', grade: 5 } })

lessons = await timeback.lessons.list()
math_lessons = await timeback.lessons.list({"course": {"subject": "Math", "grade": 5}})

`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.

string

required

The lesson identifier (from lessons.list()).

string

required

The student’s Timeback ID.

boolean

default:"false"

Start a fresh attempt instead of resuming. Behaves the same as the client forceNew option.

Return type

Response shape (not executable)

{
    lessonId: string
    lessonType: LessonType
    attempt?: number
    score: number
    questionCount?: number
    seenQuestions: number
    finalized: boolean
}

Examples

const result = await timeback.lessons.start({ lesson: 'lesson-1', student: 'tb_abc' })
const fresh = await timeback.lessons.start({ lesson: 'lesson-1', student: 'tb_abc', forceNew: true })

result = await timeback.lessons.start({"lesson": "lesson-1", "student": "tb_abc"})
fresh = await timeback.lessons.start({"lesson": "lesson-1", "student": "tb_abc", "force_new": True})

`timeback.lessons.next(input)`

Returns the next question(s) for a lesson attempt. The return type depends on lesson type:

powerpath-100: returns a single LessonQuestion
All other types: returns a LessonQuestionBatch with all questions

string

required

The lesson identifier.

string

required

The student’s Timeback ID.

LessonType

Pass "powerpath-100" for adaptive single-question delivery. If omitted, the server inspects progress and routes adaptive lessons accordingly; a contradictory explicit type is rejected.

Return type

Response shape (not executable)

// Single question (powerpath-100)
LessonQuestion

// Batch (quiz, test-out, etc.)
{
    questions: LessonQuestion[]
    answeredIds: string[]
    score: number
    finalized: boolean
    complete: boolean
}

Examples

// Quiz — returns all questions as a batch
const batch = await timeback.lessons.next({ lesson: 'lesson-1', student: 'tb_abc' })

// Adaptive — returns one question at a time
const question = await timeback.lessons.next({
    lesson: 'lesson-1',
    student: 'tb_abc',
    lessonType: 'powerpath-100',
})

# Quiz — returns all questions as a batch
batch = await timeback.lessons.next({"lesson": "lesson-1", "student": "tb_abc"})

# Adaptive — returns one question at a time
question = await timeback.lessons.next({
    "lesson": "lesson-1",
    "student": "tb_abc",
    "lesson_type": "powerpath-100",
})

`timeback.lessons.submit(input)`

Submits a student’s answer to a lesson question.

string

required

The lesson identifier.

string

required

The student’s Timeback ID.

string

required

The question ID being answered (from LessonQuestion.id).

string

required

The student’s selected answer.

Return type

Response shape (not executable)

{
    correct: boolean
    score: number
    complete: boolean
    questionResult?: unknown
}

Examples

const result = await timeback.lessons.submit({
    lesson: 'lesson-1',
    student: 'tb_abc',
    question: 'q-42',
    response: 'B',
})

result = await timeback.lessons.submit({
    "lesson": "lesson-1",
    "student": "tb_abc",
    "question": "q-42",
    "response": "B",
})

`timeback.lessons.complete(input)`

Attempts linear finalization and returns progress, with the limitations described for session.complete() above. Unlike the client method, it does not flush time tracking.

string

required

The lesson identifier.

string

required

The student’s Timeback ID.

Return type

Response shape (not executable)

{
    lessonType: LessonType
    attempt?: number
    score: number
    totalQuestions?: number
    correctQuestions?: number
    accuracy?: number
    finalized: boolean
}

Examples

const result = await timeback.lessons.complete({ lesson: 'lesson-1', student: 'tb_abc' })

result = await timeback.lessons.complete({"lesson": "lesson-1", "student": "tb_abc"})

`timeback.lessons.attempts(input)`

Lists all attempts for a lesson/student pair. Same return type as the client lessons.attempts().

string

required

The lesson identifier.

string

required

The student’s Timeback ID.

Examples

const attempts = await timeback.lessons.attempts({ lesson: 'lesson-1', student: 'tb_abc' })

attempts = await timeback.lessons.attempts({"lesson": "lesson-1", "student": "tb_abc"})

`timeback.lessons.attemptDetails(input)`

Returns raw progress data for a specific attempt. See client lessons.attemptDetails() for the discriminated return shape.

string

required

The lesson identifier.

string

required

The student’s Timeback ID.

number

required

Which attempt to review (1, 2, 3, …).

Examples

const details = await timeback.lessons.attemptDetails({
    lesson: 'lesson-1',
    student: 'tb_abc',
    attempt: 1,
})

details = await timeback.lessons.attempt_details({
    "lesson": "lesson-1",
    "student": "tb_abc",
    "attempt": 1,
})

​Client

​lessons.list()

​Return type

​Examples

​lessons.start()

​Examples

​Lesson session

​Properties

​Methods

​LessonQuestion

​LessonSubmitResult

​LessonSessionCompleteResult

​lessons.attempts()

​Return type

​lessons.attemptDetails()

​Return type

​LessonAttemptQuestion

​getLessonAttemptQuestions()

​Server

​timeback.lessons.list(input?)

​Examples

​timeback.lessons.start(input)

​Return type

​Examples

​timeback.lessons.next(input)

​Return type

​Examples

​timeback.lessons.submit(input)

​Return type

​Examples

​timeback.lessons.complete(input)

​Return type

​Examples

​timeback.lessons.attempts(input)

​Examples

​timeback.lessons.attemptDetails(input)

​Examples

Client

`lessons.list()`

Return type

Examples

`lessons.start()`

Examples

Lesson session

Properties

Methods

`LessonQuestion`

`LessonSubmitResult`

`LessonSessionCompleteResult`

`lessons.attempts()`

Return type

`lessons.attemptDetails()`

Return type

`LessonAttemptQuestion`

`getLessonAttemptQuestions()`

Server

`timeback.lessons.list(input?)`

Examples

`timeback.lessons.start(input)`

Return type

Examples

`timeback.lessons.next(input)`

Return type

Examples

`timeback.lessons.submit(input)`

Return type

Examples

`timeback.lessons.complete(input)`

Return type

Examples

`timeback.lessons.attempts(input)`

Examples

`timeback.lessons.attemptDetails(input)`

Examples