Referencia de los endpoints expuestos por la API Express. Todos aceptan y devuelven JSON con errores estructurados { "error": "mensaje" }.
username.{
"username": "ada"
}
201 Created con { id, username, created_at } cuando se crea.200 OK con el mismo payload si ya existía.400 Bad Request si falta username.200 OK con { id, username, created_at }.404 Not Found si el usuario no existe.{
"topic": "aprender redes neuronales",
"userId": 1
}
202 Accepted con { message, topic, requestId } cuando la tarea fue encolada.400 Bad Request si falta topic o userId.study_path_requests en estado pending, publica generateStudyPath y devuelve el requestId que se debe monitorear.200 OK con { request, modules? }. Cuando request.study_path_id está presente, incluye modules con image_url.404 Not Found si el identificador no existe.userId (opcional) para filtrar.200 OK con un arreglo de { id, user_id, topic, created_at }.200 OK con un arreglo de módulos que incluyen image_url cuando ya fue generada.200 OK con el módulo o 404 Not Found.{
"studyPathId": 5
}
202 Accepted si se encola, 400 si falta studyPathId.distance.study_modules.{
"text": "contenido del modulo",
"userId": 1,
"moduleId": 23
}
202 Accepted con { "jobId": "uuid" }.generateTTS; el worker genera audio con Gemini y guarda audio_url en Vercel Blob.200 OK con status, y cuando concluye agrega audioUrl, moduleId, userId.404 Not Found si no existe el ID.userId, moduleId, status (opcionales).200 OK con hasta 50 trabajos ordenados por created_at descendente.generateQuiz; el worker usa quizService y llena quizzes y questions.200 OK con { quiz, questions }.404 Not Found si aún no se generó.{
"userId": 1,
"answers": [{ "questionId": 10, "selectedOptionIndex": 2 }]
}
200 OK con attemptId, score y detalle de correcciones.{
"userId": 1,
"moduleId": 23
}
201 Created con el progreso y logros otorgados, 409 Conflict si ya estaba completado.200 OK con arreglos requests, studyPaths, pendingModules, quizzes, ttsJobs, achievements, recentProgress.prompt a Gemini, que puede llamar herramientas para tareas.{
"prompt": "Que deberia hacer hoy?"
}
200 OK con { "text": "..." } cuando Gemini responde directo.200 OK con { "toolResult": { ... } } cuando ejecuta funciones (add_task, get_tasks, update_task_status, get_daily_recommendations).400 Bad Request si faltan argumentos.req.log para trazabilidad.context en Pino) para depuración.