Lesson plans API

Lesson plans group ordered lesson IDs for a client. The external contract is read-only; plan and lesson authoring remains outside this guide.

Use ClientToken: <client-token> for a backend integration or Authorization: Bearer <firebase-id-token> for a signed-in user. See Activities authentication.

List lesson plans

GET /api/lesson-plans

The list route requires clientId:

/api/lesson-plans?clientId=your-client-id&tags=beginner,strength

The successful response is a 200 JSON array:

[
  {
    "id": "plan-123",
    "clientId": "your-client-id",
    "title": {
      "en": "Strength starter",
      "zh-Hant": "力量入門"
    },
    "description": {
      "en": "A two-week strength plan."
    },
    "planImage": "https://cdn.example.com/plan.jpg",
    "lessons": ["lesson-123", "lesson-456"],
    "tags": ["beginner", "strength"],
    "targetAreas": ["legs"],
    "duration": 14
  }
]

The response is the array itself. The older { data: ... } response description does not match the current handler.

Read one lesson plan

GET /api/lesson-plans/{id}

The clientId query parameter is optional and falls back to the request host. Add includeLessonSession=true when the embedded lesson data should retain each lesson's session configuration:

/api/lesson-plans/plan-123?clientId=your-client-id&includeLessonSession=true

The successful response is the lesson-plan object itself. Its lessonsData contains the resolved lesson configurations. By default, the handler removes each lesson's sessions and relatedLessons fields from that embedded data. With includeLessonSession=true, it keeps sessions but still removes relatedLessons.

The plan model may include the legacy planName and planDescription fields alongside the preferred localized title and description values. It can also include tags and targetAreas.

The handler returns 404 with Lesson Plan not found when the plan ID is missing for the resolved client, and 401 for failed authentication.