Skip to main content

Modules & Lessons

Modules and lessons form the core content hierarchy of a class. A module groups related lessons. Lessons contain materials, assignments, and an AI chat assistant context.

Both resources share the same visibility lifecycle: DRAFT → PUBLISHED. Only published content is visible to students.

Module Entity​

{
  "id": "mod_123",
  "class_id": "cls_123",
  "title": "Introduction to Sorting",
  "description": "Covers basic sorting algorithms.",
  "visibility_state": "DRAFT",
  "order_index": 1
}

visibility_state values: DRAFT, PUBLISHED

Lesson Entity​

{
  "id": "les_456",
  "class_id": "cls_123",
  "module_id": "mod_123",
  "title": "Bubble Sort",
  "description": "Step-by-step walkthrough of bubble sort.",
  "visibility_state": "DRAFT",
  "hidden_prompt": "Only answer questions related to sorting algorithms.",
  "order_index": 1
}

Field notes:

  • hidden_prompt — a system-level instruction injected into the AI assistant context for this lesson. Never returned to students; only visible to teachers and admins.
  • order_index — 1-based display order within the parent module.

Module Endpoints​

GET /api/v1/classes/{classId}/modules​

List all published modules for a class.

Authentication: Required — approved class member or global ADMIN.

Response: Ordered list of published module objects.

GET /api/v1/classes/{classId}/drafts/modules​

List all modules for a class, including drafts.

Authentication: Required — class TEACHER or global ADMIN.

Response: Ordered list of all module objects regardless of visibility_state.

POST /api/v1/classes/{classId}/modules​

Create a new module in draft state.

Authentication: Required — class TEACHER or global ADMIN.

Request:

{
  "title": "Introduction to Sorting",
  "description": "Covers basic sorting algorithms.",
  "order_index": 1
}

Response: Created module object with visibility_state: "DRAFT" and 201 Created.

GET /api/v1/modules/{id}​

Retrieve a single module by ID.

Authentication: Required — students see only published modules; teachers/admins see all.

PATCH /api/v1/modules/{id}​

Update module title, description, or order_index.

Authentication: Required — class TEACHER or global ADMIN.

Request: Any subset of { "title", "description", "order_index" }.

POST /api/v1/modules/{id}/publish​

Transition a module from DRAFT to PUBLISHED, making it visible to students.

Authentication: Required — class TEACHER or global ADMIN.

Request body: Empty.

POST /api/v1/modules/{id}/unpublish​

Revert a published module back to DRAFT. The module is immediately hidden from students.

Authentication: Required — class TEACHER or global ADMIN.

Request body: Empty.

DELETE /api/v1/modules/{id}​

Soft-delete a module. The module and all its lessons are hidden from all users. Data is retained server-side.

Authentication: Required — class TEACHER or global ADMIN.

Response: 204 No Content.

Lesson Endpoints​

GET /api/v1/modules/{moduleId}/lessons​

List all published lessons within a module.

Authentication: Required — approved class member or global ADMIN.

Response: Ordered list of published lesson objects (without hidden_prompt).

GET /api/v1/classes/{classId}/drafts/lessons​

List all lessons for a class, including drafts, across all modules.

Authentication: Required — class TEACHER or global ADMIN.

Response: All lesson objects including hidden_prompt.

POST /api/v1/modules/{moduleId}/lessons​

Create a new lesson in draft state within a module.

Authentication: Required — class TEACHER or global ADMIN.

Request:

{
  "title": "Bubble Sort",
  "description": "Step-by-step walkthrough of bubble sort.",
  "order_index": 1
}

Response: Created lesson object with 201 Created.

GET /api/v1/lessons/{id}​

Retrieve a single lesson by ID.

Authentication: Required — students see only published lessons; teachers/admins see all lessons including hidden_prompt.

PATCH /api/v1/lessons/{id}​

Update lesson title, description, or order_index.

Authentication: Required — class TEACHER or global ADMIN.

Request: Any subset of { "title", "description", "order_index" }.

POST /api/v1/lessons/{id}/publish​

Publish a lesson, making it visible to students.

Authentication: Required — class TEACHER or global ADMIN.

Request body: Empty.

POST /api/v1/lessons/{id}/unpublish​

Revert a lesson to draft, hiding it from students.

Authentication: Required — class TEACHER or global ADMIN.

Request body: Empty.

DELETE /api/v1/lessons/{id}​

Soft-delete a lesson and all its child content (materials, assignments, chats).

Authentication: Required — class TEACHER or global ADMIN.

Response: 204 No Content.

PATCH /api/v1/lessons/{id}/hidden-prompt​

Set or update the lesson's hidden system prompt. This prompt is prepended to every AI chat session in this lesson to shape assistant behavior (e.g. "Only answer questions related to Python data types.").

Authentication: Required — class TEACHER or global ADMIN.

Request:

{
  "hidden_prompt": "Only answer questions related to Python data types."
}

Set hidden_prompt to null or an empty string to clear the prompt.

Response: Updated lesson object.