Eve library

25.1.1.3 — Minerva REST API Endpoint Inventory

Guide

Revision 1

On this page

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#

  1. Local (email/password): bcrypt hashing, account lockout (5 attempts → 5min), password policy (8+ chars, upper/lower/digits)
  2. JWT: HS256, configurable TTL, token rotation with old secret support
  3. OAuth2: Google, Microsoft, GitHub with PKCE + CSRF protection
  4. SAML: Entity ID, SSO/ACS URLs, X509 certificates
  5. Magic Links: Token-based passwordless auth
  6. 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)#

  1. CORSMiddleware — allow_origins: ["*"], credentials: true
  2. RateLimitMiddleware — sliding window, 60/min, 1000/hr, burst 20/sec, 2x for auth users
  3. RequestIDMiddleware — UUID per request, X-Request-ID header
  4. LegacyMiddleware — Backward compat (if enabled)
  5. ResponseCacheMiddleware — Immutable response caching

Rate Limit Headers#

text
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 60
Retry-After: 30  (when 429)

Error Response Format#

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#

  1. JWT auth with token rotation — Production-ready, supports key migration
  2. OAuth2 multi-provider — Google, Microsoft, GitHub with PKCE
  3. RBAC + resource-based auth — Clean permission model
  4. Rate limiting with sliding window — Per-user, burst protection, exponential penalty
  5. Async job pattern — 202 for generation, polling for status
  6. Version control + rollback — Course version diffs, rollback with backup
  7. Multi-format export — JSON, HTML, PDF, EPUB textbooks
  8. WebSocket collaboration — Real-time editing with presence
  9. Standard error format — Consistent error codes, correlation IDs
  10. Pagination — Cursor-based with total counts

Technical Debt to DISCARD#

  1. auth.py monolith — 1,476 lines, needs decomposition into auth/, jwt/, oauth/, mfa/
  2. CORS wildcard — allow_origins: ["*"] is insecure for production
  3. In-memory persistence — Fine for dev, but default should be real DB
  4. Lazy loading via __getattr__ — Masks import issues
  5. No API versioning headers — Only URI-based, no Accept header negotiation
  6. Hardcoded entity names — "Minerva Lite API" throughout
  7. Mock server in production code — Should be in tests/
  8. No GraphQL — REST-only, no alternative query interface
  9. Duplicate import patterns — Same patterns repeated across endpoint files
  10. No request compression — Missing gzip/brotli support