curl --request POST \
  --url https://api.alpha-1edtech.ai/edubridge/progression/custom-hole-filling-course \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "studentEmail": "student@alpha.school",
  "subject": "Reading",
  "grade": "3",
  "app": "mobymax",
  "lessons": [
    {
      "lessonId": "mobymax_reading_1654_g3",
      "lessonName": "Identify and explain personification",
      "order": 1
    },
    {
      "lessonId": "mobymax_informational_text_1321_g3",
      "lessonName": "Distinguish fact from opinion",
      "order": 2
    }
  ],
  "next": "end of course"
}
'

{
  "jobId": "8cf5f85e-3efc-425a-af0b-a2be695ee4bd",
  "message": "Custom HF course creation started"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

Progression

Create a custom hole-filling course (async)

Creates a custom hole-filling course for a student with specific lessons you choose. Returns 202 with a jobId immediately — the course is created asynchronously.

How it works

Looks up the student by email
Creates lesson assignments in the target app
Creates a course in OneRoster with the assigned lessons
Removes the student from existing same-subject courses (protected courses like Manual XP are kept) — unless skipUnenroll is true
Enrolls the student in the new course

If enrollment fails, any removed courses are automatically restored (unless unenrollment was skipped). Progress and failures are reported via Google Chat notifications.

Picking lessons

For Bridge apps (mobymax, lalilo, freckle, vocabloco, anton, edia), use GET /edubridge/progression/catalog to browse available lessons, then pass the lessonId values into the lessons array.

For the native OneRoster apps (timeback, timeback_learn, alphawrite, alpha_read), /catalog does not apply and no external assignments are created. For timeback_learn, Math lessonId values are source course-component sourcedIds, while Science values are resource sourcedIds. For the other native apps, lessonId values are existing OneRoster resource sourcedIds (for alpha_read, use the article resource sourcedId, e.g. article_4100001; requires subject Reading).

Validation rules

Grade: Accepts PK, PreK, Pre-K, Pre-Kindergarten, K, KG, Kindergarten, or 0–12. Canonicalized to a numeric string (PK = -1, K = 0). Values like 3rd or banana are rejected.

next: What happens after the student completes the course. Accepts:

A test type: end of course, test out, or placement (case-insensitive, flexible spacing)
A course UUID from an active course sequence — the student will be enrolled in that course next

assignmentId: Must be a positive integer if provided. Resolved automatically from existing enrollments if omitted.

POST

edubridge

progression

custom-hole-filling-course

curl --request POST \
  --url https://api.alpha-1edtech.ai/edubridge/progression/custom-hole-filling-course \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "studentEmail": "student@alpha.school",
  "subject": "Reading",
  "grade": "3",
  "app": "mobymax",
  "lessons": [
    {
      "lessonId": "mobymax_reading_1654_g3",
      "lessonName": "Identify and explain personification",
      "order": 1
    },
    {
      "lessonId": "mobymax_informational_text_1321_g3",
      "lessonName": "Distinguish fact from opinion",
      "order": 2
    }
  ],
  "next": "end of course"
}
'

{
  "jobId": "8cf5f85e-3efc-425a-af0b-a2be695ee4bd",
  "message": "Custom HF course creation started"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

{
  "error": "<string>",
  "details": "<unknown>"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

studentEmail

string<email>

required

The student's email address.

Example:

"alice@alpha.school"

subject

enum<string>

required

Academic subject. Supported values: Math, Language, Reading, Writing, Vocabulary, Science.

Available options:

Math,

Language,

Reading,

Writing,

Vocabulary,

Science

Example:

"Reading"

grade

string

required

Grade level. Accepted values:

Canonical: -1 (Pre-K), 0 (K), 1 through 12
Aliases (case-insensitive): PK, PreK, Pre-K, Pre-Kindergarten, K, KG, Kindergarten

AP (grade 13), partial numerics (e.g. 3rd), and unrecognized strings are rejected with 400.

Minimum string length: 1

Example:

"3"

app

enum<string>

required

Learning app that owns the lessons. When app is timeback, timeback_learn, alphawrite, or alpha_read, the flow links existing OneRoster resources directly — no Bridge call is made. For timeback_learn, Math lessonId values must be source course-component sourcedIds while Science values must be resource sourcedIds. For alphawrite and alpha_read, lessonId values must be existing OneRoster resource sourcedIds (for alpha_read, the article resource sourcedId, e.g. article_4100001). alpha_read requires subject Reading.

Available options:

mobymax,

lalilo,

freckle,

vocabloco,

anton,

edia,

timeback,

timeback_learn,

alphawrite,

alpha_read

Example:

"mobymax"

lessons

object[]

required

Lessons to include in the custom hole-filling course. At least 1 required. For large sets (>100), lessons are batched automatically across multiple Bridge calls.

Minimum array length: 1

Show child attributes

string

required

Post-completion action. Accepts:

Test-type strings (case-insensitive, whitespace/hyphens/underscores ignored): end of course, test out, placement. Also accepts variant spellings like End Of Course, EndOfCourse, end-of-course, end_of_course, TEST OUT, Test-Out, etc. Normalized to assessment + the canonical test type.
Course UUID — a lowercase UUID referencing a course in an active course sequence for the given subject. Validated server-side: the course must exist, appear in an active sequence, and be the most recent courseReference on its stage (historical/swapped-out courses are rejected).

Any other value is rejected with 400.

Minimum string length: 1

Example:

"end of course"

assignmentId

integer

AlphaTest assignment ID. If omitted, the server attempts to resolve it by scanning the student's existing same-subject enrollments for course metadata containing assignmentId. Must be a positive integer.

baseCourseSourcedId

string

Base course sourced ID for hole-filling lineage tracking. If omitted, the server attempts to resolve it from the student's existing same-subject enrollments.

gapAnalysisId

string

Gap analysis record ID for metadata tracking.

missedQuestions

string[]

List of missed question IDs for metadata tracking.

skipUnenroll

boolean

When true, skip unenrolling the student from other active courses of the same subject. By default (false/omitted), the student is unenrolled from all same-subject courses before enrolling in the new HF course.

Example:

false

origin

string

Origin identifier for the assignment that triggered this custom HF. Propagated to course metadata and used when assigning the follow-up test, so AlphaTest's analysis rules resolve the correct origin. Defaults to 'progression' if omitted.

Example:

"timeback_ui"

Response

Job accepted — course creation started

jobId

string<uuid>

required

Unique job identifier for tracking. The course is created asynchronously.

Example:

"8cf5f85e-3efc-425a-af0b-a2be695ee4bd"

message

string

required

Confirmation message

Allowed value: "Custom HF course creation started"

⌘I