Eve library

Content Templates API Documentation

Guide

Revision 1

On this page

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#

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

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

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

json
{
  "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 type
  • tradition (optional): Spiritual tradition
  • difficulty (optional): Difficulty level
  • minDuration (optional): Minimum duration in minutes
  • maxDuration (optional): Maximum duration in minutes
  • tags (optional): Comma-separated tags

Response: 200 OK

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

json
{
  "userId": "string"
}

Response: 201 Created

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

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

json
{
  "criterionId": "string",
  "value": 1 | 2 | 3 | 4 | 5
}

Response: 200 OK

Complete Session#

POST /sessions/:sessionId/complete

Mark a session as completed.

Request Body:

json
{
  "notes": "string (optional)"
}

Response: 200 OK

Get User Sessions#

GET /users/:userId/sessions

Retrieve session history for a user.

Response: 200 OK

json
{
  "sessions": [...],
  "count": number
}

Data Models#

ContentTemplate#

typescript
{
  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#

typescript
{
  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#

typescript
{
  id: string;
  text: string;
  category: string;
  order: number;
  required: boolean;
  status: "pending" | "in-progress" | "completed" | "skipped";
  completedAt?: Date;
  notes?: string;
}

RatingCriterion#

typescript
{
  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#

typescript
{
  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

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Template title cannot be empty"
  }
}

404 Not Found

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Template 'tpl_xyz' not found"
  }
}

500 Internal Server Error

json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Examples#

Create a Meditation Template#

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

bash
curl -X GET "http://localhost:3007/v1/ai/content-templates/search?type=meditation&difficulty=beginner" \
  -H "Authorization: Bearer YOUR_TOKEN"

Start a Practice Session#

bash
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