Source: oshun/minerva/minerva/api/ (81 files) Analysis date: 2026-02-28
Purpose: Document all endpoints, auth, middleware for @metis/api-client
Overview#
- Framework: FastAPI + Pydantic
- Server: Starlette ASGI
- Base URL:
/api/v1
- Auth: JWT (HS256) + OAuth2 (Google, Microsoft, GitHub) + SAML + Magic
Links + TOTP MFA
- Docs: Auto-generated at
/docs (Swagger) and /redoc
- Total files: 81 Python files
Complete Endpoint Inventory#
A. Health & Status#
| Method |
Path |
Auth |
Description |
| GET |
/api/v1/health |
None |
Service health + version |
B. Authentication#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/auth/login |
None |
Email/password login → JWT tokens |
| POST |
/api/v1/auth/refresh |
Bearer |
Refresh access token |
| POST |
/api/v1/auth/logout |
Bearer |
Revoke tokens |
C. User Management#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/users |
None |
Create user account |
| GET |
/api/v1/users/me |
Bearer |
Get current user profile |
| PATCH |
/api/v1/users/me |
Bearer |
Update profile |
D. Course Management#
| Method |
Path |
Auth |
Description |
| GET |
/api/v1/courses |
None |
List courses (paginated, filterable) |
| GET |
/api/v1/courses/{id} |
None |
Get single course |
| POST |
/api/v1/courses |
Bearer+CREATE_COURSE |
Create course |
| GET |
/api/v1/courses/{id}/modules |
None |
List course modules |
| POST |
/api/v1/courses/{id}/modules |
Bearer+CREATE_COURSE |
Create module |
| GET |
/api/v1/modules/{id}/lessons |
None |
List module lessons |
| POST |
/api/v1/modules/{id}/lessons |
Bearer+CREATE_COURSE |
Create lesson |
E. AI Course Generation (Async)#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/courses/generate |
Bearer+CREATE_COURSE |
Start AI generation → 202 |
| GET |
/api/v1/generation-jobs/{id} |
Bearer+CREATE_COURSE |
Poll job status |
| POST |
/api/v1/courses/{id}/refine |
Bearer+CREATE_COURSE |
Start refinement → 202 |
| DELETE |
/api/v1/generation-jobs/{id} |
Bearer+CREATE_COURSE |
Cancel generation |
F. Version Control & Rollback#
| Method |
Path |
Auth |
Description |
| GET |
/api/v1/courses/{id}/versions |
Bearer |
List all versions |
| GET |
/api/v1/courses/{id}/versions/{v}/diff |
Bearer |
Get version diff |
| POST |
/api/v1/courses/{id}/rollback |
Bearer |
Rollback to version |
G. Export & Artifacts#
| Method |
Path |
Auth |
Description |
| GET |
/api/v1/courses/{id}/exports/textbook |
Bearer |
List textbook exports (JSON, HTML, PDF, EPUB) |
| GET |
/api/v1/courses/{id}/exports/textbook/{key} |
Bearer |
Download export |
| GET |
/api/v1/courses/{id}/manifests |
Bearer |
List asset manifests |
| GET |
/api/v1/courses/{id}/manifests/{key} |
Bearer |
Download manifest |
| POST |
/api/v1/courses/{id}/exports/presentations |
Bearer |
Generate presentation exports |
H. Assets#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/lessons/{id}/assets |
Bearer |
Upload lesson asset |
| GET |
/api/v1/lessons/{id}/assets |
None |
List lesson assets |
| DELETE |
/api/v1/assets/{id} |
Bearer |
Delete asset |
I. Assessment#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/courses/{id}/assessments |
Bearer |
Create assessment |
| POST |
/api/v1/assessments/{id}/submit |
Bearer |
Submit answers → score |
J. Search & Recommendations#
| Method |
Path |
Auth |
Description |
| GET |
/api/v1/search/courses |
None |
Full-text course search |
| GET |
/api/v1/recommendations |
Bearer |
Personalized recommendations |
K. Workflows#
| Method |
Path |
Auth |
Description |
| POST |
/api/v1/workflows/start |
Bearer |
Start agent workflow → 202 |
| GET |
/api/v1/workflows/{id}/status |
Bearer |
Get workflow status |
| DELETE |
/api/v1/workflows/{id} |
Bearer |
Cancel workflow |
L. Real-Time Collaboration (WebSocket)#
| Type |
Path |
Auth |
Description |
| WS |
/api/collaboration/ws/{project_id} |
Query params |
Real-time editing |
| GET |
/api/collaboration/projects/{id}/users |
Bearer |
Active collaborators |
| POST |
/api/collaboration/projects/{id}/events |
Bearer |
Broadcast event |
| POST |
/api/collaboration/notifications |
Bearer |
Send notification |
| GET |
/api/collaboration/stats |
Bearer+ADMIN |
Collaboration stats |
| GET |
/api/collaboration/health |
Bearer |
Service health |
Authentication System#
Providers#
- Local (email/password): bcrypt hashing, account lockout (5 attempts →
5min), password policy (8+ chars, upper/lower/digits)
- JWT: HS256, configurable TTL, token rotation with old secret support
- OAuth2: Google, Microsoft, GitHub with PKCE + CSRF protection
- SAML: Entity ID, SSO/ACS URLs, X509 certificates
- Magic Links: Token-based passwordless auth
- TOTP MFA: RFC6238, 6-digit codes, backup codes, Fernet-encrypted secrets
Token Structure#
json
{
"user_id": "string",
"username": "string",
"role": "student|educator|admin|moderator|guest",
"exp": "datetime",
"iat": "datetime",
"type": "access|refresh"
}
Authorization (RBAC)#
| Role |
Permissions |
| STUDENT |
READ_COURSE |
| EDUCATOR |
READ, CREATE, UPDATE, DELETE course |
| MODERATOR |
+ MODERATE_CONTENT, VIEW_ANALYTICS |
| ADMIN |
+ MANAGE_USERS, ADMIN_SYSTEM |
| GUEST |
Read-only via endpoint restrictions |
Middleware Stack (Order)#
- CORSMiddleware — allow_origins: ["*"], credentials: true
- RateLimitMiddleware — sliding window, 60/min, 1000/hr, burst 20/sec, 2x
for auth users
- RequestIDMiddleware — UUID per request, X-Request-ID header
- LegacyMiddleware — Backward compat (if enabled)
- ResponseCacheMiddleware — Immutable response caching
text
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 60
Retry-After: 30 (when 429)
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable message",
"detail": [
/* validation details */
],
"correlation_id": "uuid"
},
"timestamp": "ISO8601",
"request_id": "uuid"
}
| Status |
Code |
Meaning |
| 200 |
OK |
Success |
| 201 |
CREATED |
Resource created |
| 202 |
ACCEPTED |
Async job queued |
| 204 |
NO_CONTENT |
Delete success |
| 400 |
BAD_REQUEST |
Invalid params |
| 401 |
UNAUTHORIZED |
Missing/invalid auth |
| 403 |
FORBIDDEN |
Insufficient perms |
| 404 |
NOT_FOUND |
Resource not found |
| 409 |
CONFLICT |
State conflict |
| 422 |
UNPROCESSABLE |
Validation error |
| 429 |
TOO_MANY_REQUESTS |
Rate limited |
| 500 |
INTERNAL_ERROR |
Server error |
| 502 |
BAD_GATEWAY |
External service down |
Key Data Models#
CourseCreateRequest#
text
title: string (1-200 chars)
description: string (10-2000 chars)
subject: CourseSubject (enum)
level: beginner | intermediate | advanced | expert
tags: string[] (max 10)
duration_hours: float (0.5-1000)
language: string (ISO 639-1)
CourseGenerationRequest#
text
title: string (3-200 chars)
description: string (20-2000 chars)
subject: CourseSubject
grade_level: elementary | middle_school | high_school | undergraduate | graduate | professional
syllabus_id: string? (uploaded document)
target_duration_hours: float (1-200)
language: string
max_refinement_rounds: int (0-10)
enable_multimedia: boolean
tags: string[] (max 10)
UserModel#
text
user_id: UUID
username: string (^[a-zA-Z0-9_-]+$)
email: EmailStr
first_name, last_name: string?
role: STUDENT | EDUCATOR | MODERATOR | ADMIN | GUEST
is_active, is_verified: boolean
profile_image: string?
bio: string? (max 500)
preferences: Record<string, any>
created_at, last_login: datetime
Persistence Layer#
Repository pattern with in-memory (dev) and MongoDB (prod) backends:
UserRepository — CRUD + unique username/email
CourseRepository — CRUD + pagination + filtering
LibraryAssetRepository — File asset management
MaterialRepository — Learning material CRUD
File Organization (81 files)#
text
api/
├── Core (7): main_api, auth (1476L!), models (1213L), auth_singletons, exceptions, errors, repositories
├── Features (13): course_generation, refinement, websocket, tutoring, assessment, lesson_player, knowledge_graph, search, recommendations, cms, frontend_api
├── Batch (6): bulk_import (api, service, models, endpoints), web_content_batch
├── Models (5): content_models, search_models, experiments_models, web_content_batch_models
├── Utilities (5): pagination, sorting, idempotency, deprecation, versioned_routes
├── Middleware (4): rate_limiter, response_cache, legacy_middleware
├── WebSocket (4): adaptive_api, adaptive_manager, adaptive_models
├── Additional (10): lms_sync, research_sharing, learning_path, recommendation_engines
└── Dev (2): mock_server, __init__
Features to KEEP#
- JWT auth with token rotation — Production-ready, supports key migration
- OAuth2 multi-provider — Google, Microsoft, GitHub with PKCE
- RBAC + resource-based auth — Clean permission model
- Rate limiting with sliding window — Per-user, burst protection,
exponential penalty
- Async job pattern — 202 for generation, polling for status
- Version control + rollback — Course version diffs, rollback with backup
- Multi-format export — JSON, HTML, PDF, EPUB textbooks
- WebSocket collaboration — Real-time editing with presence
- Standard error format — Consistent error codes, correlation IDs
- Pagination — Cursor-based with total counts
Technical Debt to DISCARD#
- auth.py monolith — 1,476 lines, needs decomposition into auth/, jwt/,
oauth/, mfa/
- CORS wildcard —
allow_origins: ["*"] is insecure for production
- In-memory persistence — Fine for dev, but default should be real DB
- Lazy loading via
__getattr__ — Masks import issues
- No API versioning headers — Only URI-based, no Accept header negotiation
- Hardcoded entity names — "Minerva Lite API" throughout
- Mock server in production code — Should be in tests/
- No GraphQL — REST-only, no alternative query interface
- Duplicate import patterns — Same patterns repeated across endpoint files
- No request compression — Missing gzip/brotli support