This document provides comprehensive documentation for the Lilith Content Service Lesson Management API, including CRUD operations, ordering, prerequisites, versioning, and localization.
Overview#
The Lesson Management API enables management of course lessons with:
- CRUD Operations: Full create, read, update, delete for lessons
- Ordering: Reorder lessons, move to position, swap positions
- Prerequisites: Define and check lesson dependencies
- Status Workflow: Draft → Review → Published → Archived workflow
- Versioning: Version history with snapshots and rollback
- Localization: Multi-language support with translation tracking
- Engagement Metrics: View and completion tracking
Table of Contents#
- Lesson Types
- CRUD Operations
- Course Queries
- Ordering
- Prerequisites
- Status Workflow
- Versioning
- Localization
- Engagement Metrics
- Error Handling
Lesson Types#
Content Types#
| Type | Description |
|---|---|
video |
Video lesson with optional timed transcript |
audio |
Audio lesson with optional transcript |
text |
Text-based content (markdown/HTML) |
quiz |
Quiz with questions and answers |
exercise |
Practice exercise |
meditation |
Guided meditation content |
interactive |
Interactive content with custom configuration |
Status Types#
| Status | Description |
|---|---|
draft |
Initial creation state |
review |
Pending editorial review |
published |
Live and accessible |
archived |
Removed from active use |
deleted |
Soft-deleted |
Lesson Object#
{
"id": "uuid",
"courseId": "uuid",
"slug": "introduction-to-meditation",
"title": "Introduction to Meditation",
"description": "Learn the basics of meditation",
"content": "# Welcome\n\nThis lesson introduces...",
"type": "video",
"durationMinutes": 15,
"sortOrder": 1,
"chapterNumber": 1,
"chapterTitle": "Getting Started",
"videoUrl": "https://cdn.lilith.app/videos/lesson-1.mp4",
"audioUrl": null,
"thumbnailUrl": "https://cdn.lilith.app/thumbnails/lesson-1.jpg",
"mediaAssetId": "uuid",
"transcript": "Welcome to this lesson...",
"timedTranscript": [
{ "start": 0, "end": 5.5, "text": "Welcome to this lesson" }
],
"isPreview": true,
"isPremium": false,
"status": "published",
"publishedAt": "2024-01-01T00:00:00.000Z",
"viewCount": 1500,
"completionCount": 1200,
"averageCompletionPercent": 92.5,
"deletedAt": null,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"prerequisites": ["uuid-of-prerequisite-lesson"]
}
CRUD Operations#
Create Lesson#
Create a new lesson within a course.
Endpoint: POST /v1/courses/:courseId/lessons
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
courseId |
uuid | Parent course identifier |
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
slug |
string | Yes | URL-friendly identifier (lowercase, hyphens only) |
title |
string | Yes | Lesson title (1-500 characters) |
description |
string | No | Lesson description |
content |
string | No | Lesson content (markdown) |
type |
string | No | Lesson type (default: text) |
durationMinutes |
integer | No | Expected duration |
sortOrder |
integer | No | Position in course |
chapterNumber |
integer | No | Chapter grouping |
chapterTitle |
string | No | Chapter title |
videoUrl |
string | No | Video URL (for video type) |
audioUrl |
string | No | Audio URL (for audio type) |
thumbnailUrl |
string | No | Thumbnail image URL |
mediaAssetId |
uuid | No | Reference to media asset |
transcript |
string | No | Text transcript |
timedTranscript |
array | No | Timed captions array |
isPreview |
boolean | No | Available for preview (default: false) |
isPremium |
boolean | No | Premium content (default: false) |
prerequisites |
uuid[] | No | Array of prerequisite lesson IDs |
Request:
curl -X POST "https://api.lilith.app/v1/courses/course_123/lessons" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"slug": "breathing-basics",
"title": "Breathing Basics",
"description": "Learn fundamental breathing techniques",
"type": "video",
"durationMinutes": 10,
"chapterNumber": 1,
"chapterTitle": "Foundations",
"videoUrl": "https://cdn.lilith.app/videos/breathing.mp4",
"isPreview": true
}'
Response (201 Created):
{
"id": "lesson_abc123",
"courseId": "course_123",
"slug": "breathing-basics",
"title": "Breathing Basics",
"description": "Learn fundamental breathing techniques",
"type": "video",
"durationMinutes": 10,
"sortOrder": 1,
"chapterNumber": 1,
"chapterTitle": "Foundations",
"videoUrl": "https://cdn.lilith.app/videos/breathing.mp4",
"isPreview": true,
"isPremium": false,
"status": "draft",
"viewCount": 0,
"completionCount": 0,
"averageCompletionPercent": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
List Lessons (Course)#
Retrieve all lessons for a specific course.
Endpoint: GET /v1/courses/:courseId/lessons
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status |
string | Filter by status |
type |
string | Filter by lesson type |
chapterNumber |
integer | Filter by chapter |
isPreview |
boolean | Filter preview lessons |
isPremium |
boolean | Filter premium lessons |
page |
integer | Page number (default: 1) |
limit |
integer | Items per page (max: 200, default: 50) |
sortBy |
string | Sort field (default: sort_order) |
sortOrder |
string | asc or desc (default: asc) |
Request:
curl -X GET "https://api.lilith.app/v1/courses/course_123/lessons?status=published&limit=20" \
-H "Authorization: Bearer <access_token>"
Response:
{
"items": [
{
"id": "lesson_abc123",
"title": "Breathing Basics",
"sortOrder": 1,
"chapterNumber": 1,
"status": "published"
}
],
"total": 15,
"page": 1,
"limit": 20,
"totalPages": 1,
"hasNextPage": false,
"hasPreviousPage": false
}
List All Lessons#
Retrieve all lessons across courses with filtering.
Endpoint: GET /v1/lessons
Query Parameters: Same as course-specific list, plus:
| Parameter | Type | Description |
|---|---|---|
courseId |
uuid | Filter by course |
Request:
curl -X GET "https://api.lilith.app/v1/lessons?type=video&isPremium=false" \
-H "Authorization: Bearer <access_token>"
Get Lesson by ID#
Retrieve a specific lesson.
Endpoint: GET /v1/lessons/:lessonId
Request:
curl -X GET "https://api.lilith.app/v1/lessons/lesson_abc123" \
-H "Authorization: Bearer <access_token>"
Get Lesson by Slug#
Retrieve a lesson by its slug within a course.
Endpoint: GET /v1/courses/:courseId/lessons/by-slug/:slug
Request:
curl -X GET "https://api.lilith.app/v1/courses/course_123/lessons/by-slug/breathing-basics" \
-H "Authorization: Bearer <access_token>"
Update Lesson#
Update an existing lesson.
Endpoint: PUT /v1/lessons/:lessonId or PATCH /v1/lessons/:lessonId
Request:
curl -X PUT "https://api.lilith.app/v1/lessons/lesson_abc123" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"title": "Advanced Breathing Basics",
"durationMinutes": 15
}'
Delete Lesson#
Delete a lesson (soft delete by default).
Endpoint: DELETE /v1/lessons/:lessonId
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
hard |
boolean | Perform hard delete (default: false) |
Request:
curl -X DELETE "https://api.lilith.app/v1/lessons/lesson_abc123" \
-H "Authorization: Bearer <access_token>"
Response: 204 No Content
Restore Lesson#
Restore a soft-deleted lesson.
Endpoint: POST /v1/lessons/:lessonId/restore
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/restore" \
-H "Authorization: Bearer <access_token>"
Course Queries#
Get Chapters#
Retrieve lessons organized by chapter.
Endpoint: GET /v1/courses/:courseId/chapters
Response:
{
"chapters": [
{
"chapterNumber": 1,
"chapterTitle": "Foundations",
"lessons": [
{ "id": "lesson_1", "title": "Introduction", "sortOrder": 1 },
{ "id": "lesson_2", "title": "Breathing Basics", "sortOrder": 2 }
]
},
{
"chapterNumber": 2,
"chapterTitle": "Advanced Techniques",
"lessons": [
{ "id": "lesson_3", "title": "Deep Breathing", "sortOrder": 3 }
]
}
]
}
Get Next Lesson#
Retrieve the next lesson in sequence.
Endpoint: GET /v1/lessons/:lessonId/next
Response: Returns the next lesson object or 404 if none exists.
Get Previous Lesson#
Retrieve the previous lesson in sequence.
Endpoint: GET /v1/lessons/:lessonId/previous
Response: Returns the previous lesson object or 404 if none exists.
Ordering#
Reorder Lessons#
Reorder all lessons in a course by specifying the desired order.
Endpoint: POST /v1/courses/:courseId/lessons/reorder
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
lessonIds |
uuid[] | Yes | Lesson IDs in desired order |
Request:
curl -X POST "https://api.lilith.app/v1/courses/course_123/lessons/reorder" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"lessonIds": [
"lesson_3",
"lesson_1",
"lesson_2"
]
}'
Response:
{
"lessons": [
{ "id": "lesson_3", "sortOrder": 0 },
{ "id": "lesson_1", "sortOrder": 1 },
{ "id": "lesson_2", "sortOrder": 2 }
]
}
Move Lesson to Position#
Move a specific lesson to a new position.
Endpoint: POST /v1/lessons/:lessonId/move
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
position |
integer | Yes | Target position (0-indexed) |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/move" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "position": 0 }'
Swap Lesson Order#
Swap positions of two lessons.
Endpoint: POST /v1/lessons/:lessonId/swap/:otherLessonId
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_1/swap/lesson_2" \
-H "Authorization: Bearer <access_token>"
Response:
{ "success": true }
Prerequisites#
Get Prerequisites#
Retrieve prerequisites for a lesson.
Endpoint: GET /v1/lessons/:lessonId/prerequisites
Response:
{
"prerequisites": [
{
"id": "prereq_1",
"lessonId": "lesson_abc123",
"prerequisiteLessonId": "lesson_intro",
"isRequired": true,
"createdAt": "2024-01-01T00:00:00.000Z"
}
]
}
Add Prerequisite#
Add a prerequisite to a lesson.
Endpoint: POST /v1/lessons/:lessonId/prerequisites
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
prerequisiteLessonId |
uuid | Yes | Prerequisite lesson ID |
isRequired |
boolean | No | Is prerequisite required (default: true) |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_advanced/prerequisites" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"prerequisiteLessonId": "lesson_basics",
"isRequired": true
}'
Remove Prerequisite#
Remove a prerequisite from a lesson.
Endpoint: DELETE /v1/lessons/:lessonId/prerequisites/:prerequisiteLessonId
Response: 204 No Content
Get Dependents#
Retrieve lessons that depend on this lesson as a prerequisite.
Endpoint: GET /v1/lessons/:lessonId/dependents
Response:
{
"dependents": [
{ "id": "lesson_advanced", "title": "Advanced Techniques" },
{ "id": "lesson_expert", "title": "Expert Level" }
]
}
Check Prerequisites Met#
Check if a user has completed all prerequisites.
Endpoint: POST /v1/lessons/:lessonId/check-prerequisites
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
completedLessonIds |
uuid[] | Yes | Array of completed lesson IDs |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_advanced/check-prerequisites" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"completedLessonIds": ["lesson_intro", "lesson_basics"]
}'
Response:
{ "prerequisitesMet": true }
Status Workflow#
Status Transition Diagram#
┌─────────┐ ┌────────┐ ┌───────────┐
│ draft │ ──→ │ review │ ──→ │ published │
└────┬────┘ └───┬────┘ └─────┬─────┘
│ │ │
│ │ ↓
│ ↓ ┌──────────┐
└─────────────→ deleted ←── │ archived │
└──────────┘
Allowed Transitions#
| From | To |
|---|---|
draft |
review, deleted |
review |
draft, published, deleted |
published |
archived, deleted |
archived |
draft, published, deleted |
deleted |
(none) |
Transition Status#
Manually transition lesson status.
Endpoint: POST /v1/lessons/:lessonId/status
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
status |
string | Yes | Target status |
reason |
string | No | Reason for transition |
authorId |
uuid | No | Author performing action |
authorName |
string | No | Author name |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/status" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"status": "review",
"reason": "Ready for editorial review"
}'
Publish Lesson#
Quick publish action (transitions through review if needed).
Endpoint: POST /v1/lessons/:lessonId/publish
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
authorId |
uuid | No | Publishing author ID |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/publish" \
-H "Authorization: Bearer <access_token>"
Archive Lesson#
Archive a published lesson.
Endpoint: POST /v1/lessons/:lessonId/archive
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/archive" \
-H "Authorization: Bearer <access_token>"
Get Allowed Transitions#
Retrieve valid status transitions for a lesson.
Endpoint: GET /v1/lessons/:lessonId/allowed-transitions
Response:
{
"currentStatus": "review",
"allowedTransitions": ["draft", "published", "deleted"]
}
Versioning#
List Versions#
Retrieve all versions for a lesson.
Endpoint: GET /v1/lessons/:lessonId/versions
Response:
{
"versions": [
{
"id": "version_123",
"contentType": "lesson",
"contentId": "lesson_abc123",
"versionNumber": 3,
"versionLabel": null,
"contentSnapshot": { "title": "Current Title", "content": "..." },
"changeSummary": "Updated content for clarity",
"changes": [
{ "field": "content", "oldValue": "old text", "newValue": "new text" }
],
"authorId": "user_123",
"authorName": "John Doe",
"status": "published",
"isCurrent": true,
"publishedAt": "2024-01-01T00:00:00.000Z",
"createdAt": "2024-01-01T00:00:00.000Z"
}
]
}
Get Current Version#
Retrieve the current active version.
Endpoint: GET /v1/lessons/:lessonId/versions/current
Get Specific Version#
Retrieve a specific version by number.
Endpoint: GET /v1/lessons/:lessonId/versions/:versionNumber
Create Version#
Create a new version snapshot.
Endpoint: POST /v1/lessons/:lessonId/versions
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
changeSummary |
string | No | Description of changes |
authorId |
uuid | No | Author creating version |
authorName |
string | No | Author name |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/versions" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"changeSummary": "Major content update for 2024"
}'
Restore Version#
Restore a previous version.
Endpoint: POST /v1/lessons/:lessonId/versions/:versionNumber/restore
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
authorId |
uuid | No | Author performing restore |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/versions/2/restore" \
-H "Authorization: Bearer <access_token>"
Localization#
Translation Status#
| Status | Description |
|---|---|
not_started |
Translation not begun |
in_progress |
Translation in progress |
machine_translated |
Machine translation complete |
human_reviewed |
Human review complete |
approved |
Ready for publication |
List Locales#
Retrieve all locales for a lesson.
Endpoint: GET /v1/lessons/:lessonId/locales
Response:
{
"locales": [
{
"id": "locale_en",
"locale": "en",
"isDefault": true,
"title": "Breathing Basics",
"translationStatus": "approved"
},
{
"id": "locale_es",
"locale": "es",
"isDefault": false,
"title": "Fundamentos de Respiración",
"translationStatus": "human_reviewed"
}
]
}
Create Locale#
Create a new locale translation.
Endpoint: POST /v1/lessons/:lessonId/locales
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
locale |
string | Yes | Locale code (e.g., es, fr-CA) |
isDefault |
boolean | No | Set as default locale |
title |
string | No | Translated title |
description |
string | No | Translated description |
content |
string | No | Translated content |
localizedData |
object | No | Additional localized fields |
translatorId |
uuid | No | Translator user ID |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/locales" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"locale": "es",
"title": "Fundamentos de Respiración",
"description": "Aprende técnicas básicas de respiración"
}'
Get Locale#
Retrieve a specific locale.
Endpoint: GET /v1/lessons/:lessonId/locales/:locale
Update Locale#
Update a locale translation.
Endpoint: PUT /v1/lessons/:lessonId/locales/:locale
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | No | Translated title |
description |
string | No | Translated description |
content |
string | No | Translated content |
summary |
string | No | Translated summary |
localizedData |
object | No | Additional localized fields |
translationStatus |
string | No | Translation status |
translatorId |
uuid | No | Translator ID |
reviewerId |
uuid | No | Reviewer ID |
translationQualityScore |
number | No | Quality score (0-100) |
Delete Locale#
Delete a locale translation.
Endpoint: DELETE /v1/lessons/:lessonId/locales/:locale
Response: 204 No Content
Set Default Locale#
Set a locale as the default.
Endpoint: POST /v1/lessons/:lessonId/locales/:locale/set-default
Response:
{ "success": true }
Engagement Metrics#
Record View#
Increment view count for a lesson.
Endpoint: POST /v1/lessons/:lessonId/view
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/view" \
-H "Authorization: Bearer <access_token>"
Response:
{ "success": true }
Record Completion#
Record lesson completion and update average completion percent.
Endpoint: POST /v1/lessons/:lessonId/complete
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
completionPercent |
number | No | Completion percentage (0-100) |
Request:
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/complete" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "completionPercent": 95 }'
Error Handling#
Error Codes#
| Code | HTTP Status | Description |
|---|---|---|
NOT_FOUND |
404 | Lesson not found |
INVALID_TRANSITION |
400 | Invalid status transition |
CIRCULAR_DEPENDENCY |
400 | Circular prerequisite detected |
INVALID_PREREQUISITE |
400 | Prerequisites must be from same course |
INVALID_SWAP |
400 | Lessons must be from same course to swap |
DUPLICATE |
409 | Lesson with slug already exists in course |
INVALID_VERSION |
400 | Version number must be an integer |
INTERNAL_ERROR |
500 | Unexpected server error |
Example Error Response#
{
"code": "INVALID_TRANSITION",
"message": "Invalid status transition from 'draft' to 'archived'"
}
SDK Integration#
TypeScript/JavaScript#
import { LilithClient } from '@lilith/sdk';
const client = new LilithClient({
apiKey: process.env.LILITH_API_KEY,
});
// Create a lesson
const lesson = await client.content.createLesson('course_123', {
slug: 'breathing-basics',
title: 'Breathing Basics',
type: 'video',
durationMinutes: 10,
isPreview: true,
});
// List lessons with filtering
const lessons = await client.content.listLessons('course_123', {
status: 'published',
type: 'video',
limit: 20,
});
// Add prerequisite
await client.content.addPrerequisite('lesson_advanced', {
prerequisiteLessonId: 'lesson_basics',
isRequired: true,
});
// Check prerequisites
const { prerequisitesMet } = await client.content.checkPrerequisites(
'lesson_advanced',
{
completedLessonIds: ['lesson_intro', 'lesson_basics'],
}
);
// Publish lesson
await client.content.publishLesson('lesson_abc123');
// Create version
await client.content.createVersion('lesson_abc123', {
changeSummary: 'Updated content for clarity',
});
// Create locale
await client.content.createLocale('lesson_abc123', {
locale: 'es',
title: 'Fundamentos de Respiración',
});
// Record view
await client.content.recordView('lesson_abc123');
Related Documentation#
- Course API - Parent course management
- Media API - Media asset management
- Authentication - API authentication
- Error Codes - Complete error reference
Questions?#
- Technical Support: api-support@lilith.app
- Documentation: GitHub Issues