TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/vanegasjoseignacio2-cyber/Eco-It/llms.txt
Use this file to discover all available pages before exploring further.
/api/admin route group powers the Eco-It back-office dashboard. Every endpoint in this group is protected by JWT authentication (verificarToken) and requires at minimum the admin role. Certain destructive operations — such as deleting notifications, purging audit logs, or changing a user’s role — additionally require the superadmin role. All requests must include a valid Authorization: Bearer <token> header.
Users
GET /api/admin/usuarios
Returns a paginated-ready list of every registered user, sorted newest-first. Passwords, reset tokens, and expiry dates are excluded from the response. Each user object is augmented with a liveisOnline flag derived from the active Socket.IO connection map.
Auth: Admin
true on a successful fetch.Array of user objects. Sensitive fields (
password, resetPasswordToken, resetPasswordExpires) are stripped.GET /api/admin/stats
Returns aggregated KPI statistics for the admin dashboard, including total users, recycling points, AI chat queries, and rich chart data for the last 30 days and the current year. Auth: Admintrue on success.Total number of registered accounts.
Number of users with an active Socket.IO session at query time.
Accounts created since midnight today (Colombia/Bogotá timezone).
Sum of
puntos across all user accounts.Cumulative AI chat messages sent by users (images excluded).
Chat messages sent today.
Nested chart-ready data arrays.
GET /api/admin/admin
Returns the name, email, and role of the currently authenticated admin. Useful for rendering the dashboard header or validating the active session. Auth: AdminA welcome string:
"Bienvenido al panel de administrador".DELETE /api/admin/users/:id
Permanently deletes a user account and all associated data. An audit log entry is automatically created. An admin cannot delete their own account. Auth: Admin| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the user to delete. |
true on successful deletion."Usuario eliminado exitosamente" or an error description.PATCH /api/admin/users/:id/ban
Bans a user for a specified number of days. Sets the user’sstatus to "banned", records banHasta (expiry date) and banReason, emits a real-time user:banned Socket.IO event to the affected user’s active connections, and creates a Notification document visible to all admins.
Auth: Admin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the target user. |
Duration of the ban in days.
Human-readable reason for the ban, stored in
banReason and the generated notification.true on success.E.g.
"Usuario baneado por 7 días".The updated user document reflecting the new banned status.
An admin cannot ban themselves. Attempting to do so returns HTTP 400. A real-time Socket.IO event (
user:banned) is emitted to the target user’s open sockets so they are immediately logged out on the client side.PATCH /api/admin/users/:id/unban
Lifts an active ban by resetting the user’sstatus to "active" and clearing banHasta. Emits a user:unbanned Socket.IO event to the affected user in real time and writes an audit log entry.
Auth: Admin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the target user. |
true on success."Usuario desbaneado exitosamente".The updated user document with
status: "active" and banHasta: null.PATCH /api/admin/users/:id/role
Changes a user’s role to either"user" or "admin". If the target user is currently "active" and connected, their Socket.IO room membership is updated instantly (joined or removed from the admins room).
Auth: Superadmin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the target user. |
New role to assign. Must be either
"user" or "admin". The value "superadmin" is explicitly rejected.true on success.Confirmation message including the new role, e.g.
"El rol del usuario ha sido cambiado a admin".The updated user document.
Notifications
Notifications are system-generated events (e.g. ban events, content alerts) stored in MongoDB. They auto-expire after 7 days via a TTL index. Each notification tracks which admin users have read it via thereadBy array.
GET /api/admin/notifications
Returns the 50 most recent notifications, sorted by date descending. Each notification is augmented with a per-requesting-adminread boolean.
Auth: Admin
true on success.Array of notification objects.
PATCH /api/admin/notifications/mark-read
Marks all notifications as read for the requesting admin by adding their user ID to thereadBy array of every notification not yet read by them.
Auth: Admin
true on success."Notificaciones marcadas como leídas".PATCH /api/admin/notifications/:id/mark-read
Marks a single notification as read for the requesting admin. Auth: Admin| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the notification. |
true on success."Notificación marcada como leída".DELETE /api/admin/notifications/all
Permanently deletes all notifications from the database. Auth: Superadmintrue on success."Todas las notificaciones eliminadas de la base de datos".DELETE /api/admin/notifications/:id
Deletes a single notification by its ID. Auth: Superadmin| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the notification to delete. |
true on success."Notificación eliminada de la base de datos".Audit Logs
Audit logs are immutable records of significant admin actions (bans, unbans, role changes, deletions, slide creations, etc.). They are written automatically by thecreateAuditLog utility and auto-expire after 7 days via a MongoDB TTL index.
GET /api/admin/audit
Returns the 50 most recent audit log entries, sorted newest-first. Auth: Admintrue on success.Array of audit log objects.
Audit logs are read-only by design for regular admins. Only superadmins can delete entries, and even then, the TTL index will automatically clean up records older than 7 days regardless.
DELETE /api/admin/audit/:id
Deletes a single audit log entry by its ID before its natural TTL expiry. Auth: Superadmin| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the audit log entry. |
true on success."Registro eliminado de la base de datos".DELETE /api/admin/audit/all
Wipes the entire audit log collection. Auth: Superadmintrue on success."Todos los registros eliminados de la base de datos".Map Points (Admin)
These endpoints manage the recycling point markers displayed on the public Eco-It map. Mutations emit a real-timemap:updated Socket.IO event to all connected clients so the map refreshes instantly without requiring a page reload. Images are uploaded to and hosted on Cloudinary under the ecoit_map_points folder.
GET /api/admin/map/points
Returns all recycling points (both active and inactive, both user-visible and hidden), sorted newest-first. This is the admin-facing counterpart of the public map endpoint. Auth: Admintrue on success.Full PuntoReciclaje documents including admin-only fields like
activo and visibleToUser.POST /api/admin/map/points
Creates a new recycling map point. If theimagen field contains a base64 data URI, it is uploaded to Cloudinary and the resulting secure URL is stored in its place.
Auth: Admin
Display name of the recycling point shown on the map and in listings.
Category of the point. Must be one of:
"recycling", "ecobottle", "truck", "container", "green_zone". Defaults to "recycling".Latitude of the point in decimal degrees (e.g.
4.7110 for Bogotá).Longitude of the point in decimal degrees (e.g.
-74.0721 for Bogotá).Optional text description of the location or accepted materials.
Base64-encoded data URI (e.g.
"data:image/png;base64,...") or an existing URL. If a data URI is provided, it is uploaded to Cloudinary and replaced with the resulting secure URL.Whether the point is immediately active after creation.
Whether the point should appear on the public-facing user map.
true on creation.The newly created PuntoReciclaje document.
PATCH /api/admin/map/points/:id
Updates any fields of an existing recycling point. Partial updates are supported — only provide the fields you wish to change. Ifimagen is a new base64 data URI, it is re-uploaded to Cloudinary.
Auth: Admin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the point to update. |
Updated display name.
Updated type. Same enum as POST.
Updated latitude.
Updated longitude.
Updated description.
New base64 data URI or Cloudinary URL.
Updated active state.
Updated user-visibility flag.
true on success.The updated PuntoReciclaje document (returned with
{ new: true }).DELETE /api/admin/map/points/:id
Permanently removes a recycling point from the database and triggers a livemap:updated event for all connected clients.
Auth: Admin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the point to delete. |
true on success."Punto eliminado correctamente".PATCH /api/admin/map/points/:id/toggle
Flips theactivo boolean of a recycling point (active → inactive or inactive → active) without requiring the full point object in the request body. Emits map:updated in real time.
Auth: Admin
| Path parameter | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the point to toggle. |
true on success.The updated PuntoReciclaje document with the new
activo state reflected.