API Version: 0.1.0
Overview#
The Content Templates API provides endpoints for creating, managing, and using structured lecture and meditation templates with built-in self-assessment capabilities.
Base URL#
http://localhost:3007/v1/ai
Authentication#
All endpoints require authentication via Bearer token in the Authorization header.
Endpoints#
Create Template#
POST /content-templates
Creates a new content template.
Request Body:
{
"type": "lecture" | "meditation" | "practice" | "reflection",
"title": "string",
"description": "string",
"tradition": "string (optional)",
"difficulty": "beginner" | "intermediate" | "advanced" | "expert",
"duration": number,
"tags": ["string"],
"sections": [{
"title": "string",
"content": "string",
"type": "text" | "audio_cue" | "visual_cue" | "instruction" | "reflection_prompt",
"duration": number (optional),
"order": number
}],
"checklist": [{
"text": "string",
"category": "string",
"order": number,
"required": boolean
}] (optional),
"ratingCriteria": [{
"dimension": "string",
"question": "string",
"scale": {
"min": 1,
"max": 5,
"labels": {
"1": "string",
"2": "string",
"3": "string",
"4": "string",
"5": "string"
}
},
"order": number
}] (optional)
}
Response: 201 Created
{
"id": "tpl_xyz",
"type": "lecture",
"title": "Introduction to Mindfulness",
"version": "1.0.0",
"createdAt": "2025-10-03T00:00:00Z",
...
}
List All Templates#
GET /content-templates
Returns all available templates.
Response: 200 OK
{
"templates": [...],
"count": number
}
Search Templates#
GET
/content-templates/search?type={type}&tradition={tradition}&difficulty={difficulty}&minDuration={min}&maxDuration={max}&tags={tag1,tag2}
Search templates with filters.
Query Parameters:
type(optional): Template typetradition(optional): Spiritual traditiondifficulty(optional): Difficulty levelminDuration(optional): Minimum duration in minutesmaxDuration(optional): Maximum duration in minutestags(optional): Comma-separated tags
Response: 200 OK
{
"templates": [...],
"count": number
}
Get Template#
GET /content-templates/:id
Retrieve a specific template by ID.
Response: 200 OK or 404 Not Found
Update Template#
PUT /content-templates/:id
Update an existing template. Increments version.
Request Body: Same as Create Template (partial updates supported)
Response: 200 OK or 404 Not Found
Delete Template#
DELETE /content-templates/:id
Delete a template.
Response: 204 No Content or 404 Not Found
Start Session#
POST /content-templates/:id/sessions
Start a practice session with a template.
Request Body:
{
"userId": "string"
}
Response: 201 Created
{
"sessionId": "ses_xyz",
"templateId": "tpl_abc",
"userId": "user_123",
"startedAt": "2025-10-03T00:00:00Z"
}
Update Checklist Item#
PUT /sessions/:sessionId/checklist/:itemId
Update a checklist item status during a session.
Request Body:
{
"status": "pending" | "in-progress" | "completed" | "skipped",
"notes": "string (optional)"
}
Response: 200 OK
Add Rating#
POST /sessions/:sessionId/ratings
Submit a self-rating for a session.
Request Body:
{
"criterionId": "string",
"value": 1 | 2 | 3 | 4 | 5
}
Response: 200 OK
Complete Session#
POST /sessions/:sessionId/complete
Mark a session as completed.
Request Body:
{
"notes": "string (optional)"
}
Response: 200 OK
Get User Sessions#
GET /users/:userId/sessions
Retrieve session history for a user.
Response: 200 OK
{
"sessions": [...],
"count": number
}
Data Models#
ContentTemplate#
{
id: string;
type: "lecture" | "meditation" | "practice" | "reflection";
title: string;
description: string;
tradition?: string;
difficulty: "beginner" | "intermediate" | "advanced" | "expert";
duration: number; // in minutes
tags: string[];
sections: TemplateSection[];
checklist?: ChecklistItem[];
ratingCriteria?: RatingCriterion[];
createdAt: Date;
updatedAt: Date;
version: string;
}
TemplateSection#
{
id: string;
title: string;
content: string;
type: "text" | "audio_cue" | "visual_cue" | "instruction" | "reflection_prompt";
duration?: number; // in seconds
order: number;
metadata?: Record<string, unknown>;
}
ChecklistItem#
{
id: string;
text: string;
category: string;
order: number;
required: boolean;
status: "pending" | "in-progress" | "completed" | "skipped";
completedAt?: Date;
notes?: string;
}
RatingCriterion#
{
id: string;
dimension: string;
question: string;
scale: {
min: 1 | 2 | 3 | 4 | 5;
max: 1 | 2 | 3 | 4 | 5;
labels: Record<1 | 2 | 3 | 4 | 5, string>;
}
order: number;
}
TemplateSession#
{
id: string;
templateId: string;
userId: string;
startedAt: Date;
completedAt?: Date;
checklistProgress: Map<string, ChecklistItemStatus>;
ratings: Map<string, RatingScale>;
notes: string;
duration: number; // actual duration in minutes
}
Error Responses#
All endpoints return standard error responses:
400 Bad Request
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Template title cannot be empty"
}
}
404 Not Found
{
"error": {
"code": "NOT_FOUND",
"message": "Template 'tpl_xyz' not found"
}
}
500 Internal Server Error
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Examples#
Create a Meditation Template#
curl -X POST http://localhost:3007/v1/ai/content-templates \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "meditation",
"title": "Mindful Breathing Practice",
"description": "A guided breathing meditation for beginners",
"tradition": "Buddhist",
"difficulty": "beginner",
"duration": 10,
"tags": ["breathing", "mindfulness", "beginner"],
"sections": [
{
"title": "Introduction",
"content": "Find a comfortable seated position...",
"type": "instruction",
"order": 1
},
{
"title": "Main Practice",
"content": "Focus on your natural breath...",
"type": "audio_cue",
"duration": 480,
"order": 2
},
{
"title": "Closing",
"content": "Slowly return your awareness...",
"type": "instruction",
"order": 3
}
],
"checklist": [
{
"text": "Did you maintain focus on your breath?",
"category": "practice",
"order": 1,
"required": false
},
{
"text": "Did you notice when your mind wandered?",
"category": "awareness",
"order": 2,
"required": false
}
],
"ratingCriteria": [
{
"dimension": "relaxation",
"question": "How relaxed did you feel during the practice?",
"scale": {
"min": 1,
"max": 5,
"labels": {
"1": "Very tense",
"2": "Somewhat tense",
"3": "Neutral",
"4": "Somewhat relaxed",
"5": "Very relaxed"
}
},
"order": 1
}
]
}'
Search for Beginner Meditations#
curl -X GET "http://localhost:3007/v1/ai/content-templates/search?type=meditation&difficulty=beginner" \
-H "Authorization: Bearer YOUR_TOKEN"
Start a Practice Session#
curl -X POST http://localhost:3007/v1/ai/content-templates/tpl_xyz/sessions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123"
}'
Test Coverage#
The Content Templates feature has comprehensive test coverage:
- Unit Tests: 41 tests (100% code coverage)
- Integration Tests: 20 tests (all HTTP endpoints)
- Total: 61 tests passing
Implementation#
- Language: TypeScript with strict type safety
- File:
apps/lilith/svc-ai/src/content-templates.ts - Lines of Code: 356
- Dependencies: None (in-memory storage)
Limitations#
- Templates are stored in-memory (not persisted to database)
- No pagination on list endpoints
- Session data is not persisted
- No real-time synchronization across instances
Future Enhancements#
- Database persistence (PostgreSQL)
- Pagination and cursor-based navigation
- Real-time session updates via WebSocket
- Template versioning and rollback
- Template sharing and publishing
- Community ratings and reviews