# Lilith Services Endpoint Analysis Report

## Executive Summary

This report provides a comprehensive analysis of all API endpoints implemented
across the Lilith microservices architecture and compares them with the existing
OpenAPI documentation.

**Key Finding: The codebase contains approximately 410 implemented endpoints,
while the OpenAPI specification documents only 168 endpoints - indicating
significant under-documentation of the actual API surface.**

## OpenAPI Documentation Overview

- **Total Documented Endpoints**: 168
- **Documented Path Prefixes**: `/v1/`
- **Coverage Areas**: Authentication, User Management, Chat, Conversation,
  Content, Media, Meditation, Wellness, Analytics, Admin

## Implemented Endpoints by Service

### 1. Auth Service (~85 endpoints)

**Core Authentication Endpoints:**

- `GET /v1/health` - Health check
- `POST /v1/auth/logout` - User logout
- `GET /v1/auth/profile` - Get user profile
- `PATCH /v1/auth/profile` - Update user profile
- `POST /v1/auth/change-password` - Change password
- `GET /v1/auth/sessions` - List user sessions
- `DELETE /v1/auth/sessions/:sessionId` - Revoke session
- `GET /v1/auth/audit-logs` - Get audit logs

**Advanced Authentication Features:**

- `POST /v1/auth/validate` - Token validation
- `POST /v1/auth/revoke` - Token revocation
- `POST /v1/auth/password/reset` - Password reset request
- `POST /v1/auth/password/confirm` - Password reset confirmation
- `POST /v1/auth/password/change` - Password change
- `GET /v1/auth/oauth/:provider` - OAuth provider login
- `POST /v1/auth/oauth/callback` - OAuth callback
- `POST /v1/auth/social/link` - Link social account
- `POST /v1/auth/sessions/revoke-all` - Revoke all sessions

**WebAuthn & 2FA:**

- `POST /v1/auth/webauthn/registration/begin` - Begin WebAuthn registration
- `GET /v1/users/:id/webauthn/credentials` - List WebAuthn credentials
- `POST /v1/auth/2fa/enable` - Enable 2FA
- `POST /v1/auth/2fa/verify` - Verify 2FA
- `POST /v1/auth/2fa/disable` - Disable 2FA

**API Keys:**

- `POST /v1/auth/api-keys` - Create API key
- `GET /v1/auth/api-keys` - List API keys
- `DELETE /v1/auth/api-keys/:keyId` - Delete API key

**Email Verification:**

- `POST /v1/auth/verify/email` - Request email verification
- `GET /v1/auth/verify/email/:token` - Verify email token

**OAuth Providers:**

- `GET /v1/auth/oauth/providers` - List OAuth providers
- `GET /v1/auth/oauth/google` - Google OAuth
- `GET /v1/auth/oauth/github` - GitHub OAuth

**User Management:**

- `GET /v1/users/:id/profile` - Get user profile
- `PUT /v1/users/:id/profile` - Update user profile
- `POST /v1/users/:id/consent` - Record user consent
- `GET /v1/users/:id/consent-history` - Get consent history

**DSR (Data Subject Rights):**

- `POST /v1/users/:id/data-export` - Export user data
- `GET /v1/users/:id/data-export-history` - Get export history
- `POST /v1/users/:id/data-deletion` - Request data deletion
- `GET /v1/users/:id/data-deletion-history` - Get deletion history
- `POST /v1/users/:id/data-deletion/:deletionId/cancel` - Cancel deletion
- `POST /v1/users/:id/data-deletion/:deletionId/execute` - Execute deletion
- `GET /v1/users/:id/data-map` - Get data map

**Privacy & Compliance:**

- `POST /v1/privacy/policies` - Create privacy policy
- `POST /v1/privacy/policies/:policyId/versions/:version/publish` - Publish
  policy version
- `GET /v1/privacy/policies/:policyId/current` - Get current policy
- `GET /v1/privacy/policies/:policyId/versions` - List policy versions
- `GET /v1/privacy/policies/:policyId/versions/:version` - Get specific version

**Personalization:**

- `GET /v1/personalization/privacy-levels` - Get privacy levels
- `POST /v1/personalization/cleanup/expired` - Cleanup expired data
- `POST /v1/users/:id/personalization/cleanup` - Cleanup user personalization
  data
- `GET /v1/users/:id/personalization/audit-logs` - Get personalization audit
  logs
- `GET /v1/users/:id/personalization/privacy-budget` - Get privacy budget
- `POST /v1/users/:id/personalization/privacy-budget/consume` - Consume privacy
  budget
- `GET /v1/users/:id/personalization/vectors` - Get personalization vectors
- `POST /v1/users/:id/personalization/vectors` - Create personalization vectors

**Pseudonymous Authentication:**

- `POST /v1/auth/register-pseudonymous` - Register pseudonymous account
- `POST /v1/auth/login-pseudonymous` - Login pseudonymous
- `DELETE /v1/auth/account` - Delete account
- `POST /v1/auth/export` - Export data

**Magic Links:**

- `POST /v1/auth/magic-link/request` - Request magic link
- `POST /v1/auth/magic-link/authenticate` - Authenticate with magic link

**Multi-Factor Authentication:**

- `POST /v1/auth/mfa/toggle` - Toggle MFA

**Admin Endpoints:**

- `POST /v1/admin/users/:id/roles` - Assign user roles
- `GET /v1/admin/users/:id/audit-logs` - Get user audit logs

### 2. AI Service (~75 endpoints)

**Multi-Agent System:**

- `POST /v1/agents` - Create agent
- `GET /v1/agents` - List agents
- `GET /v1/agents/:agentId` - Get agent details
- `POST /v1/agents/sessions` - Create agent session
- `GET /v1/agents/sessions/:sessionId` - Get session details
- `GET /v1/agents/memory/:userId` - Get agent memory
- `POST /v1/agents/memory/:userId/store` - Store in agent memory
- `DELETE /v1/agents/memory/:userId/reset` - Reset agent memory
- `GET /v1/agents/protocols` - List agent protocols

**Content Templates:**

- `POST /v1/ai/content-templates` - Create content template
- `GET /v1/ai/content-templates` - List content templates
- `GET /v1/ai/content-templates/search` - Search content templates
- `GET /v1/ai/content-templates/:templateId` - Get template details
- `PUT /v1/ai/content-templates/:templateId` - Update template
- `DELETE /v1/ai/content-templates/:templateId` - Delete template
- `POST /v1/ai/content-templates/:templateId/sessions` - Create template session

**AI Completion & Chat:**

- `POST /v1/ai/complete` - AI text completion
- `POST /v1/chat/completion` - Chat completion
- `POST /v1/ai/chat` - AI chat
- `POST /v1/ai/completion` - Alternative completion endpoint

**AI Providers:**

- `POST /v1/ai/providers` - Add AI provider
- `GET /v1/ai/providers` - List AI providers
- `GET /v1/ai/providers/:providerId/health` - Check provider health

**Personas & Prompts:**

- `POST /v1/ai/personas/:personaKey/prompts` - Create persona prompt
- `GET /v1/ai/personas/:personaKey/prompts` - Get persona prompts
- `POST /v1/ai/templates` - Create AI template
- `GET /v1/ai/templates` - List AI templates
- `GET /v1/ai/templates/:templateId` - Get template details
- `POST /v1/ai/templates/:templateId/generate` - Generate from template
- `GET /v1/ai/content/:contentId` - Get AI content

**AI Agents:**

- `GET /v1/ai/agents` - List AI agents
- `GET /v1/ai/agents/:agentId` - Get AI agent
- `GET /v1/ai/agents/role/:role` - Get agents by role
- `GET /v1/ai/agents/capability/:capability` - Get agents by capability
- `GET /v1/ai/agents/tool/:toolName` - Get agents by tool
- `POST /v1/ai/agents/:agentId/tasks` - Create agent task
- `POST /v1/ai/tasks/:taskId/execute` - Execute agent task
- `GET /v1/ai/agents/:agentId/tool-history` - Get agent tool history

**Tools & Schemas:**

- `GET /v1/ai/tools` - List AI tools
- `GET /v1/ai/tools/:toolName` - Get tool details
- `POST /v1/ai/tools/:toolName/validate` - Validate tool
- `GET /v1/ai/tools/:toolName/schema` - Get tool schema

**Feature Flags:**

- `GET /v1/ai/feature-flags` - List feature flags
- `PUT /v1/ai/feature-flags/:flagName` - Update feature flag

**Session Management:**

- `PUT /v1/ai/sessions/:sessionId/checklist/:itemId` - Update checklist item
- `POST /v1/ai/sessions/:sessionId/ratings` - Rate session
- `POST /v1/ai/sessions/:sessionId/complete` - Complete session
- `GET /v1/ai/users/:userId/sessions` - Get user sessions

**Security & Safety:**

- `POST /v1/evaluations/golden-sets` - Create golden set evaluation
- `GET /v1/evaluations/traditions` - Get traditions
- `POST /v1/evaluations/evaluate` - Run evaluation
- `GET /v1/security/jailbreak-analytics` - Get jailbreak analytics
- `GET /v1/security/alerts` - Get security alerts
- `POST /v1/safety/escalate` - Escalate safety issue

**Tracing & Monitoring:**

- `POST /v1/tracing/llm-call` - Trace LLM call
- `POST /v1/tracing/tts-call` - Trace TTS call

**Testing:**

- `POST /v1/test/reset` - Reset test data
- `GET /v1/health` - Health check

### 3. BFF Service (~50 endpoints)

**Core BFF Features:**

- `GET /v1/health` - Health check
- `POST /v1/auth/register` - User registration
- `POST /v1/auth/login` - User login
- `POST /v1/auth/refresh` - Token refresh
- `POST /v1/auth/logout` - User logout

**Conversations:**

- `POST /v1/conversations` - Create conversation
- `GET /v1/conversations` - List conversations
- `GET /v1/conversations/:conversationId` - Get conversation
- `POST /v1/conversations/:conversationId/messages` - Add message

**Chat Features:**

- `POST /v1/chat/personalized` - Personalized chat
- `POST /v1/chat/comparative` - Comparative chat

**Circuit Breaker:**

- `GET /v1/circuit-breaker/status` - Get circuit breaker status
- `GET /v1/circuit-breaker/status/:serviceName` - Get service status
- `POST /v1/circuit-breaker/config` - Configure circuit breaker
- `POST /v1/circuit-breaker/test-failure` - Test failure

**Bulk Operations:**

- `POST /v1/bulk-operations` - Execute bulk operations

**Dashboard & Analytics:**

- `GET /v1/dashboard` - Get dashboard data
- `GET /v1/experiments` - List experiments
- `POST /v1/experiments/:experimentId/assign` - Assign to experiment

**API Versioning:**

- `GET /v1/models/versions` - Get model versions
- `POST /v1/models/negotiate` - Negotiate model version

**Content Management:**

- `GET /v1/conversation-context/:conversationId` - Get conversation context
- `POST /v1/lectures` - Create lecture
- `POST /v1/ingest` - Ingest content

**Notifications:**

- `POST /v1/notifications/test` - Test notification

**Language & Localization:**

- `POST /v1/tts:synthesize` - Synthesize speech
- `POST /v1/chat/audio` - Audio chat
- `POST /v1/stt:transcribe` - Transcribe audio
- `POST /v1/detect-language` - Detect language
- `GET /v1/users/:userId/language-preferences` - Get language preferences
- `POST /v1/users/:userId/language-preferences` - Set language preferences

**User Session & Memory:**

- `GET /v1/user-session` - Get user session
- `GET /v1/users/:userId/memory` - Get user memory
- `GET /v1/users/:userId/memory/controls` - Get memory controls

**Error Handling:**

- `GET /v1/errors/schema` - Get error schema
- `POST /v1/errors/normalize` - Normalize error
- `GET /v1/errors/test/:errorType` - Test error type
- `GET /v1/errors/recovery` - Get error recovery
- `GET /v1/errors/localization` - Get error localization
- `GET /v1/errors/context` - Get error context

**Personas:**

- `GET /v1/personas` - List personas
- `GET /v1/personas/:personaId` - Get persona
- `GET /v1/personas/category/:category` - Get personas by category

**Tracing:**

- `POST /v1/config/tracing` - Configure tracing
- `POST /v1/tracing/test` - Test tracing

**Admin:**

- `GET /v1/admin/errors/mappings` - Get error mappings
- `POST /v1/admin/errors/normalize` - Normalize admin errors
- `POST /v1/admin/errors/test` - Test admin errors

**Aggregation:**

- `POST /v1/aggregate` - Aggregate data

### 4. Conversation Service (~15 endpoints)

**Core Conversation Management:**

- `GET /v1/health` - Health check
- `POST /v1/test/reset` - Reset test data
- `GET /v1/ws/chat` - WebSocket chat endpoint
- `GET /v1/ws/status` - WebSocket status

**Conversations:**

- `POST /v1/conversations` - Create conversation
- `GET /v1/conversations` - List conversations
- `GET /v1/conversations/:conversationId/metrics` - Get conversation metrics
- `DELETE /v1/conversations/:conversationId` - Delete conversation
- `PUT /v1/conversations/:conversationId` - Update conversation

**Threads:**

- `POST /v1/conversations/threads` - Create thread
- `GET /v1/threads` - List threads
- `GET /v1/threads/:threadId` - Get thread
- `PATCH /v1/threads/:threadId` - Update thread
- `DELETE /v1/threads/:threadId` - Delete thread
- `GET /v1/threads/:threadId/messages` - Get thread messages
- `GET /v1/threads/:threadId/messages/:messageId` - Get specific message

**Chat:**

- `POST /v1/chat` - Send chat message

### 5. Content Service (~85 endpoints)

**Core Content Management:**

- `GET /v1/health` - Health check
- `POST /v1/test/reset` - Reset test data
- `GET /v1/content/:id` - Get content
- `GET /v1/content/:id/versions` - Get content versions
- `DELETE /v1/content/:id` - Delete content
- `GET /v1/content` - List content
- `POST /v1/content/:id/transition` - Transition content state

**Localization:**

- `POST /v1/content/:id/locales` - Add locale
- `GET /v1/content/:id/locales` - List locales
- `PUT /v1/content/:id/locales/:language` - Update locale
- `DELETE /v1/content/:id/locales/:language` - Delete locale
- `POST /v1/content/auto-switch` - Auto-switch locale
- `POST /v1/content/auto-switch/batch` - Batch auto-switch
- `GET /v1/content/:id/languages` - Get available languages

**Content Features:**

- `GET /v1/content/recommendations` - Get recommendations
- `GET /v1/content/facets` - Get content facets
- `GET /v1/content/search` - Search content
- `POST /v1/content/search` - Advanced search

**Translation & Cultural Context:**

- `GET /v1/content/:id/translations/compare` - Compare translations
- `GET /v1/content/:id/translations/diff` - Get translation diff
- `GET /v1/content/:id/translations/quality` - Get translation quality
- `GET /v1/content/:id/translations` - Get translations
- `GET /v1/content/translations/stats` - Get translation stats
- `POST /v1/content/:id/cultural-context` - Add cultural context
- `POST /v1/content/:id/cultural-adaptations` - Create cultural adaptations
- `POST /v1/content/:id/cultural-review` - Create cultural review
- `POST /v1/content/cultural-review/:reviewId/complete` - Complete cultural
  review
- `GET /v1/content/:id/cultural-context/:contextId` - Get cultural context
- `GET /v1/content/:id/localization-recommendations` - Get localization
  recommendations
- `GET /v1/content/:id/cultural-status` - Get cultural status

**Courses:**

- `GET /v1/courses/:courseId` - Get course
- `GET /v1/courses` - List courses
- `POST /v1/courses` - Create course
- `PUT /v1/courses/:courseId` - Update course
- `POST /v1/courses/:courseId/progress/:userId` - Create progress
- `PUT /v1/courses/:courseId/progress/:userId` - Update progress

**Course Items:**

- `POST /v1/courses/:courseId/items` - Create course item
- `GET /v1/courses/:courseId/items` - List course items
- `GET /v1/courses/:courseId/items/:itemId` - Get course item
- `PUT /v1/courses/:courseId/items/:itemId` - Update course item
- `DELETE /v1/courses/:courseId/items/:itemId` - Delete course item

**Course Progress:**

- `POST /v1/courses/:courseId/progress` - Create progress
- `PUT /v1/courses/:courseId/progress` - Update progress
- `GET /v1/courses/:courseId/progress/:userId` - Get progress
- `GET /v1/users/:userId/progress` - Get user progress

**Schedules:**

- `POST /v1/schedules` - Create schedule
- `GET /v1/schedules/:id` - Get schedule
- `PUT /v1/schedules/:id` - Update schedule
- `DELETE /v1/schedules/:id` - Delete schedule
- `GET /v1/schedules/:id/today` - Get today's schedule

**Playlists:**

- `POST /v1/playlists` - Create playlist
- `GET /v1/playlists` - List playlists
- `GET /v1/playlists/:id` - Get playlist
- `PUT /v1/playlists/:id` - Update playlist
- `DELETE /v1/playlists/:id` - Delete playlist

**Curriculum & Learning:**

- `POST /v1/curricula` - Create curriculum
- `GET /v1/curricula/:curriculumId` - Get curriculum
- `POST /v1/learning-paths` - Create learning path
- `POST /v1/competencies` - Create competency

**Scholar Features:**

- `POST /v1/scholar-notes` - Create scholar note
- `GET /v1/scholar-notes/:userId` - Get scholar notes

**Reflections:**

- `POST /v1/reflections/daily` - Create daily reflection
- `GET /v1/reflections/daily/:userId` - Get daily reflections

**Analytics:**

- `GET /v1/analytics/learning/:userId` - Get learning analytics

**Content Access & History:**

- `POST /v1/content/:id/verify-access` - Verify content access
- `POST /v1/users/:userId/history` - Add to history
- `GET /v1/users/:userId/history` - Get history
- `GET /v1/users/:userId/history/recent` - Get recent history
- `GET /v1/users/:userId/history/export` - Export history
- `GET /v1/users/:userId/history/stats` - Get history stats
- `DELETE /v1/users/:userId/history` - Clear history
- `DELETE /v1/users/:userId/history/:historyId` - Delete history item

**Resume Positions:**

- `PUT /v1/users/:userId/content/:contentId/resume` - Set resume position
- `GET /v1/users/:userId/content/:contentId/resume` - Get resume position
- `GET /v1/users/:userId/resume-positions` - Get all resume positions
- `DELETE /v1/users/:userId/content/:contentId/resume` - Clear resume position

**Content Export:**

- `GET /v1/content/:id/export/srt` - Export as SRT
- `GET /v1/content/:id/export/vtt` - Export as VTT

**Landing Pages:**

- `POST /v1/content/:id/landing-page` - Create landing page

**SEO:**

- `GET /v1/courses/sitemap/jsonld` - Get sitemap as JSON-LD

### 6. Media Service (~45 endpoints)

**Core Media Management:**

- `GET /v1/health` - Health check
- `POST /v1/media` - Upload media
- `GET /v1/media/:id` - Get media details
- `POST /v1/media/:id/signed-url` - Generate signed URL
- `POST /v1/media/:id/verify` - Verify media
- `POST /v1/media/:id/package` - Package media
- `DELETE /v1/media/:id` - Delete media

**Media Processing:**

- `POST /v1/media/:id/process` - Process media
- `GET /v1/media/:id/processing-status` - Get processing status
- `POST /v1/media/:id/normalize` - Normalize media
- `POST /v1/media/:id/silence-detection` - Detect silence
- `GET /v1/media/:id/quality-analysis` - Get quality analysis

**Storage & CDN:**

- `GET /v1/media/:id/storage-info` - Get storage info
- `POST /v1/media/:id/storage-transition` - Transition storage
- `PUT /v1/media/:id/retention` - Set retention policy
- `GET /v1/media/:id/cdn-info` - Get CDN info
- `POST /v1/media/:id/cdn-purge` - Purge from CDN
- `GET /v1/media/:id/replication-status` - Get replication status

**Waveforms & Audio:**

- `POST /v1/media/:id/waveform` - Generate waveform

**Transcripts:**

- `POST /v1/transcripts` - Create transcript
- `GET /v1/transcripts/:id/export/srt` - Export transcript as SRT
- `GET /v1/transcripts/:id/export/vtt` - Export transcript as VTT
- `GET /v1/transcripts/:id/search` - Search transcript

**Backup & Maintenance:**

- `POST /v1/media/backup-policies` - Create backup policy
- `POST /v1/media/cleanup` - Cleanup media
- `POST /v1/media/maintenance` - Perform maintenance
- `GET /v1/media/status/system` - Get system status

**Batch Operations:**

- `POST /v1/media/batch` - Batch operation
- `POST /v1/media/bulk-delete` - Bulk delete

**Analytics & Stats:**

- `GET /v1/media/storage-stats` - Get storage statistics
- `GET /v1/media/analytics` - Get media analytics
- `GET /v1/media/bucket-info` - Get bucket information

**Direct Upload:**

- `POST /v1/media/upload-direct` - Direct upload
- `POST /v1/media/:id/confirm-upload` - Confirm upload

**TTS (Text-to-Speech):**

- `GET /v1/tts/voices` - List TTS voices
- `POST /v1/tts/synthesize` - Synthesize speech
- `GET /v1/tts/jobs/:jobId` - Get TTS job
- `POST /v1/tts/batch` - Batch TTS
- `POST /v1/tts/validate-ssml` - Validate SSML
- `POST /v1/tts/voices/clone` - Clone voice
- `POST /v1/tts/effects` - Apply audio effects
- `GET /v1/tts/stats` - Get TTS statistics

**Admin & Webhooks:**

- `POST /v1/media/webhooks/test` - Test webhook
- `POST /v1/admin/bucket/initialize` - Initialize bucket
- `GET /v1/admin/bucket/lifecycle` - Get bucket lifecycle
- `POST /v1/admin/bucket/lifecycle` - Set bucket lifecycle
- `GET /v1/admin/bucket/replication` - Get bucket replication
- `POST /v1/admin/bucket/replication` - Set bucket replication
- `POST /v1/admin/bucket/notifications` - Set bucket notifications

### 7. Notification Service (~6 endpoints)

**Core Notification Features:**

- `GET /v1/health` - Health check
- `POST /v1/agents/workflows/notification` - Create notification workflow
- `GET /v1/agents/workflows` - List workflows
- `POST /v1/agents/workflows/:workflow_id/execute` - Execute workflow

**Documentation:**

- `POST /v1/docs/auto-generate` - Auto-generate documentation
- `GET /v1/docs/validation` - Validate documentation

### 8. Moderation Service (~4 endpoints)

**Core Moderation:**

- `GET /v1/health` - Health check
- `GET /v1/moderation/abstain-refer/analytics` - Get moderation analytics
- `GET /v1/safety/ecosystem/validate` - Validate safety ecosystem
- `GET /v1/filters` - Get content filters

### 9. STT Service (~35 endpoints)

**Core STT Features:**

- `GET /v1/health` - Health check
- `POST /v1/stt:transcribe` - Transcribe audio
- `POST /v1/stt:batch-transcribe` - Batch transcribe

**Models & Features:**

- `GET /v1/models` - List models
- `GET /v1/models/:modelId` - Get model details
- `GET /v1/features` - List features
- `GET /v1/languages` - List supported languages

**Vocabulary Management:**

- `POST /v1/stt/vocabulary` - Create vocabulary
- `PATCH /v1/stt/vocabulary/:vocabularyId` - Update vocabulary
- `GET /v1/stt/vocabulary` - List vocabularies
- `DELETE /v1/stt/vocabulary/:vocabularyId` - Delete vocabulary
- `POST /v1/users/:userId/vocabulary` - Create user vocabulary
- `GET /v1/users/:userId/vocabulary` - Get user vocabulary

**Advanced STT Features:**

- `GET /v1/stt/config/endpointing` - Get endpointing config
- `POST /v1/stt/config/endpointing` - Set endpointing config
- `GET /v1/stt/profanity/locales` - Get profanity filter locales
- `GET /v1/stt/profanity/wordlist/:locale` - Get profanity wordlist
- `POST /v1/stt/profanity/wordlist/:locale/words` - Add profanity words
- `GET /v1/stt/vocabulary/domains` - List vocabulary domains
- `GET /v1/stt/vocabulary/domain/:domain` - Get domain vocabulary
- `POST /v1/stt/vocabulary/domain/:domain/terms` - Add domain terms
- `GET /v1/stt/accents/supported` - Get supported accents
- `GET /v1/stt/accents/analytics/:userId` - Get accent analytics

**Jobs & Batches:**

- `GET /v1/stt/batch/:batchId` - Get batch status
- `GET /v1/stt/batches/:batchId` - Get batch status (alternative)
- `GET /v1/stt/jobs/:jobId` - Get job status
- `GET /v1/stt/jobs` - List jobs
- `DELETE /v1/stt/jobs/:jobId` - Delete job
- `GET /v1/transcriptions/:jobId` - Get transcription

**Usage & Analytics:**

- `GET /v1/usage/:userId` - Get user usage
- `GET /v1/stt/usage/:userIdOrTimeRange` - Get usage analytics

**WER (Word Error Rate) Testing:**

- `POST /v1/stt/wer/test-sets` - Create WER test set
- `GET /v1/stt/wer/test-sets` - List WER test sets
- `GET /v1/stt/wer/test-sets/:testSetId` - Get WER test set
- `POST /v1/stt/wer/evaluate` - Evaluate WER
- `GET /v1/stt/wer/results` - Get WER results
- `GET /v1/stt/wer/results/:resultId` - Get WER result
- `GET /v1/stt/wer/analytics` - Get WER analytics

### 10. Anonymization Service (~10 endpoints)

**Core Anonymization:**

- `GET /v1/health` - Health check
- `POST /v1/anonymization/jobs` - Create anonymization job
- `GET /v1/anonymization/jobs/:id` - Get anonymization job
- `POST /v1/anonymization/jobs/:id/execute` - Execute anonymization job
- `POST /v1/anonymization/k-anonymity` - Apply k-anonymity

## Gap Analysis

### Major Missing Documentation Areas

1. **Advanced Authentication Features** (~40 undocumented endpoints)
   - WebAuthn, 2FA, API keys, social login, OAuth providers
   - DSR compliance, privacy policies, consent management
   - Personalization vectors, privacy budgets, pseudonymous auth

2. **AI Service Capabilities** (~60 undocumented endpoints)
   - Multi-agent systems, content templates, tool schemas
   - AI provider management, persona prompts, feature flags
   - Security analytics, safety escalation, evaluation systems

3. **BFF Advanced Features** (~35 undocumented endpoints)
   - Circuit breaker patterns, bulk operations
   - Error normalization and handling systems
   - Language detection, memory management
   - Tracing configuration, admin error tools

4. **Content Service Extensibility** (~70 undocumented endpoints)
   - Cultural localization, adaptation workflows
   - Course progress tracking, playlist management
   - Scholar notes, reflections, learning analytics
   - History tracking, resume positions, SEO features

5. **Media Service Processing** (~35 undocumented endpoints)
   - Advanced processing workflows, quality analysis
   - CDN management, storage transitions
   - Backup policies, batch operations
   - TTS voice cloning, effects, statistics

6. **STT Service Features** (~30 undocumented endpoints)
   - Vocabulary management, domain-specific terms
   - Profanity filtering, accent analytics
   - WER testing and evaluation systems
   - Advanced usage analytics

### Documented but Potentially Missing Implementation

From the OpenAPI spec, these areas appear documented but may need implementation
verification:

1. **Meditation & Wellness APIs**
2. **Analytics Dashboard APIs**
3. **Admin Management APIs**
4. **Payment & Settlement APIs**

## Recommendations

### Immediate Actions

1. **Update OpenAPI Documentation**
   - Add ~242 undocumented endpoints to OpenAPI spec
   - Prioritize core authentication, AI, and content endpoints
   - Group endpoints by functional areas

2. **Documentation Structure**
   - Create separate OpenAPI files per service domain
   - Implement automated documentation generation from code
   - Add comprehensive examples and use cases

3. **API Consistency**
   - Standardize endpoint naming conventions
   - Ensure consistent error response formats
   - Implement consistent authentication patterns

### Long-term Improvements

1. **Automated Documentation Pipeline**
   - Extract endpoints automatically from source code
   - Generate OpenAPI specs from route definitions
   - Validate documentation against implementation

2. **API Versioning Strategy**
   - Implement proper versioning for new endpoints
   - Create deprecation policies for old endpoints
   - Document breaking changes systematically

3. **Developer Experience**
   - Create interactive API documentation
   - Generate client SDKs from OpenAPI specs
   - Provide comprehensive integration guides

## Conclusion

The Lilith platform has significantly more API endpoints implemented than
documented (410 vs 168), indicating a substantial gap in API documentation. The
implemented endpoints cover advanced features in authentication, AI processing,
content management, media processing, and speech-to-text capabilities that are
not reflected in the current OpenAPI specification.

This analysis reveals a highly feature-rich platform with sophisticated
capabilities that need proper documentation to support developer adoption and
API consumption.
