Eve library

Lesson Management API

Guide

Revision 1

On this page

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#

  1. Lesson Types
  2. CRUD Operations
  3. Course Queries
  4. Ordering
  5. Prerequisites
  6. Status Workflow
  7. Versioning
  8. Localization
  9. Engagement Metrics
  10. 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#

json
{
  "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:

bash
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):

json
{
  "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:

bash
curl -X GET "https://api.lilith.app/v1/courses/course_123/lessons?status=published&limit=20" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{
  "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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

bash
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:

json
{
  "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:

bash
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:

json
{
  "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:

bash
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:

bash
curl -X POST "https://api.lilith.app/v1/lessons/lesson_1/swap/lesson_2" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{ "success": true }

Prerequisites#

Get Prerequisites#

Retrieve prerequisites for a lesson.

Endpoint: GET /v1/lessons/:lessonId/prerequisites

Response:

json
{
  "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:

bash
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:

json
{
  "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:

bash
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:

json
{ "prerequisitesMet": true }

Status Workflow#

Status Transition Diagram#

text
┌─────────┐      ┌────────┐      ┌───────────┐
│  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:

bash
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:

bash
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:

bash
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:

json
{
  "currentStatus": "review",
  "allowedTransitions": ["draft", "published", "deleted"]
}

Versioning#

List Versions#

Retrieve all versions for a lesson.

Endpoint: GET /v1/lessons/:lessonId/versions

Response:

json
{
  "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:

bash
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:

bash
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:

json
{
  "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:

bash
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:

json
{ "success": true }

Engagement Metrics#

Record View#

Increment view count for a lesson.

Endpoint: POST /v1/lessons/:lessonId/view

Request:

bash
curl -X POST "https://api.lilith.app/v1/lessons/lesson_abc123/view" \
  -H "Authorization: Bearer <access_token>"

Response:

json
{ "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:

bash
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#

json
{
  "code": "INVALID_TRANSITION",
  "message": "Invalid status transition from 'draft' to 'archived'"
}

SDK Integration#

TypeScript/JavaScript#

typescript
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');


Questions?#

  • Technical Support: api-support@lilith.app
  • Documentation: GitHub Issues