Vanguardia EPIS exposes a RESTful API built with FastAPI that powers the school dropout early-warning dashboard. All endpoints serve JSON and are organized into three functional groups: student risk classification (which integrates an AI explanation pipeline), teacher management, and aggregate statistics for the administration dashboard.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Pierrot-01/Hackathon_epis_2026/llms.txt
Use this file to discover all available pages before exploring further.
Base URL
Interactive Documentation
FastAPI auto-generates a Swagger UI at:http://localhost:8000/redoc. Both interfaces allow you to send live requests directly from the browser without any additional tooling.
Authentication
No authentication is required. The API is configured with open CORS (allow_origins=["*"]), allowing requests from any origin. This design is intentional for local institutional deployment where access control is handled at the network level rather than the application layer.
Endpoint Reference
All endpoints are prefixed with/api/.
| Method | Path | Description |
|---|---|---|
GET | /api/health | Server health check and version |
GET | /api/estudiantes | List all students with risk classification and AI explanations |
GET | /api/estudiantes/:id_estudiante | Get a single student by ID |
POST | /api/estudiantes | Create or update a student record |
DELETE | /api/estudiantes/:id_estudiante | Delete a student by ID |
GET | /api/docentes | List all registered teachers |
POST | /api/docentes | Create or update a teacher record |
DELETE | /api/docentes/:id_docente | Delete a teacher by ID |
GET | /api/stats | Global risk-level distribution statistics |
In-Memory Session Cache
The API maintains an in-memory dictionary (_resultados_cache) keyed by student ID. This cache persists for the lifetime of the server process.
- First call to
GET /api/estudiantes: classifies all students and calls the AI explanation service for each one in parallel. This is the slow path — latency depends on the number of students and AI provider response time. - Subsequent calls: return the cached
EstudianteResultadoobjects immediately without re-running the classifier or calling the AI. - Cache bypass: pass
force_refresh=trueas a query parameter onGET /api/estudiantesorGET /api/estudiantes/{id}to force reprocessing of the student(s) and update the cache.
GET /api/stats also benefits from this cache — if results are already cached it reads nivel_riesgo directly from memory; otherwise it runs the classifier (without AI) for speed.
Response Format
All responses areapplication/json. Error responses follow FastAPI’s default structure:
200 OK— successful read, creation, or update404 Not Found— resource ID does not exist in the dataset422 Unprocessable Entity— request body failed Pydantic validation
The origen_ia Field
Every EstudianteResultado includes an origen_ia field that tells you exactly how the AI-generated explanation was sourced:
| Value | Meaning |
|---|---|
"vivo" | The explanation was generated live by the AI provider during this request. |
"fallback" | The AI call failed but a previously cached explanation was available and returned instead. |
"error_sin_cache" | The AI call failed and no cached explanation existed — explicacion and recomendacion will be null. |
"no_aplica" | No AI explanation was requested (e.g., the student’s risk level does not trigger an explanation). |
Auto-Incremented IDs
Both students and teachers use zero-padded numeric IDs auto-generated by the server:- Students:
EST-001,EST-002, …EST-NNN - Teachers:
DOC-001,DOC-002, …DOC-NNN
id in a POST body switches the endpoint into update mode rather than create mode.
Explore the API
Estudiantes
CRUD for student records, risk classification, and AI explanation endpoints.
Docentes
Create, list, update, and delete teacher records.
Estadísticas
Global risk distribution counts and percentages for the admin dashboard.
Data Model
Field-level reference for EstudianteResultado and DocenteResultado.