# 25.1.1.3 — Minerva REST API Endpoint Inventory

> 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

```
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

```
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

```
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

```
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)

```
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
