Lessons API

The lesson catalogue contains the lesson metadata and session timeline needed to start a GOFA lesson play. These endpoints are read-only in the external integration surface. Lesson authoring, subtitle changes, and catalogue administration are handled by GOFA's internal tools.

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

List lessons

GET /api/lessons

The list route requires clientId in the query string:

/api/lessons?clientId=your-client-id

When algos is omitted, the route requests VIDEO_COUNT, VIDEO_ENGAGEMENT, and VIDEO_MIRROR. Supported algorithm values also include FREE_RUN, AUDIO_DYNAMIC, AUDIO_STATIC, VIDEO_STATIC, and FITNESS_CHALLENGE.

The successful response is a 200 JSON array, not a { data: ... } envelope:

[
  {
    "id": "lesson-123",
    "clientId": "your-client-id",
    "status": "active",
    "uniqueID": "lesson-123",
    "title": {
      "en": "Balance basics",
      "zh-Hant": "平衡基礎",
      "zh-Hans": "平衡基础"
    },
    "description": {
      "en": "A guided balance lesson."
    },
    "imageUrl": "https://cdn.example.com/lesson.jpg",
    "thumbImageUrl": "https://cdn.example.com/lesson-thumb.jpg",
    "videoURLs": ["https://cdn.example.com/lesson.mp4"],
    "duration": 600,
    "isIndividual": true,
    "algorithm": "VIDEO_COUNT",
    "sessions": [
      {
        "index": 0,
        "timeout": 60,
        "videoURLs": ["https://cdn.example.com/session.mp4"],
        "rule": null
      }
    ],
    "groupByIntensity": "LOW",
    "groupByStyles": [],
    "groupByTypes": ["STRENGTH"],
    "groupByMuscles": [],
    "groupByGoals": [],
    "groupByEquipments": [],
    "groupByTrainers": [],
    "MET": 3
  }
]

The route reads the client's live lesson IDs and may include GOFA-shared live lessons. A lesson must be live for the resolved client and match the requested algorithm. The response may contain additional fields; the example focuses on the playback and catalogue fields an external integration needs.

Read one lesson

GET /api/lessons/{id}

The clientId query parameter is optional on this route. If omitted, the client is resolved from the request host:

/api/lessons/lesson-123?clientId=your-client-id

The successful response is the lesson object itself. A cache miss or a lesson that is not live for the client is returned as JSON null with status 200 by the current handler, so callers should handle that value explicitly. Authentication failures return the common 401 response.

The lesson object includes its sessions timeline. Each session has an index and may include timeout or media URLs plus an algorithm rule object. The exact rule payload is algorithm-specific.