Skip to main content

Documentation 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.

EcoBot is Eco-It’s conversational AI assistant, specialised exclusively in recycling and environmental sustainability in the Colombian context. It is powered by OpenRouter using openrouter/free as the primary model, with an automatic fallback to Google Gemini 2.5 Flash Lite (google/gemini-2.5-flash-lite) when the free-model quota is exhausted. All endpoints under /api/ai require a valid JWT and apply the verificarToken middleware — unauthenticated requests receive 401 Unauthorized.
EcoBot enforces a strict content policy. Inappropriate language in chat triggers an admin alert. Sending obscene images results in an automatic 3-day account ban. All policy violations are stored as admin notifications and broadcast via Socket.IO.

​
Text chat

​
POST /api/ai/consultar

Sends a question to EcoBot and streams the response back using Server-Sent Events (SSE). Chat history is persisted per user. Each user may have up to 50 chats; the oldest are removed automatically when the limit is exceeded. Authentication: Required. Request body
​
pregunta
string
required
The question or message to send to EcoBot. Must be a non-empty string.
​
chatId
string
Optional. The _id of an existing chat to continue. If omitted, a new chat is created and its ID is sent as the first SSE event.
Response format — Server-Sent Events The endpoint sets the following headers and streams data: lines until the model finishes: 
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
The stream contains three distinct event types, emitted in this order:
​
data: {chatId}
SSE event
First event. Always sent before any content. Contains the chat ID (new or existing) so the client can associate the stream with a chat record.
data: {"chatId":"665f1a2b3c4d5e6f7a8b9c0d"}
​
data: {content}
SSE event
Content chunk events. One or more events, each carrying a fragment of the model’s response. Concatenate all content values to build the full answer.
data: {"content":"El plástico tipo 1 (PET)"}
data: {"content":" va en la caneca blanca."}
​
data: [DONE]
SSE event
Final event. Signals that the stream is complete. Close the reader when this event is received.
data: [DONE]
JavaScript fetch example 
const response = await fetch("https://api.eco-it.app/api/ai/consultar", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({ pregunta: "¿Cómo reciclo una botella de plástico en Bogotá?" }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let chatId = null;
let fullAnswer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split("\n");

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const raw = line.slice(6).trim();

    if (raw === "[DONE]") {
      console.log("Stream complete. Full answer:", fullAnswer);
      break;
    }

    try {
      const parsed = JSON.parse(raw);
      if (parsed.chatId) {
        chatId = parsed.chatId;
        console.log("Chat ID:", chatId);
      }
      if (parsed.content) {
        fullAnswer += parsed.content;
        process.stdout.write(parsed.content); // live render
      }
    } catch {
      // ignore malformed lines
    }
  }
}
Persist the chatId received in the first SSE event. Pass it back as chatId in subsequent requests to maintain conversation context — EcoBot will load the full chat history and include it in the model’s context window.

​
Image analysis

​
POST /api/ai/analizar-imagen

Sends an image to EcoBot for recycling-focused visual analysis using Gemini 2.5 Flash Lite (multimodal). The model identifies materials in the image and advises which Colombian recycling bin colour to use. This endpoint is not streaming — it returns a complete JSON response. Authentication: Required. Request body
​
imagen
string
required
The image as a base64 data URL — e.g., "data:image/jpeg;base64,/9j/4AAQ...". Obtain this by reading a <input type="file"> with FileReader.readAsDataURL().
​
contexto
string
Optional. Additional text context to help EcoBot understand the image — e.g., "¿En qué caneca va este envase?". If omitted, the model is instructed to perform a general sustainability analysis.
​
chatId
string
Optional. Attach this analysis to an existing chat. If omitted, a new chat titled "Análisis de imagen" is created.
Response
​
success
boolean
​
data.respuesta
string
EcoBot’s analysis in plain text (no Markdown formatting). Contains bin colour recommendations based on Colombian recycling norms.
​
data.chatId
string
The _id of the chat where this analysis was saved.
curl -X POST https://api.eco-it.app/api/ai/analizar-imagen \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "imagen": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...",
    "contexto": "¿Cómo debo desechar este envase?"
  }'

{
  "success": true,
  "data": {
    "respuesta": "El envase que veo es una botella de vidrio transparente. En Colombia, el vidrio es un material aprovechable y debe depositarse en la caneca BLANCA. Asegúrate de enjuagarla antes de botarla.",
    "chatId": "665f9e1a2b3c4d5e6f7a8b01"
  }
}
If the model detects obscene content in the image, the response body will contain "ALERTA_OBSCENA:" and the user account will be automatically banned for 3 days. An admin notification is emitted via Socket.IO in real time.

​
Chat history

All chat history endpoints are scoped to the authenticated user — a user can only read or delete their own chats.

​
GET /api/ai/chats

Returns a lightweight list of all the user’s chats, sorted from most recently updated to oldest. Use this to populate a sidebar or history panel. Authentication: Required. Response
​
(array)
Chat[]
Array of chat summary objects.
​
[]._id
string
MongoDB _id of the chat.
​
[].title
string
Auto-generated title (first 40 characters of the opening question).
​
[].updatedAt
string
ISO 8601 timestamp of the last message.
curl -X GET https://api.eco-it.app/api/ai/chats \
  -H "Authorization: Bearer <token>"

[
  {
    "_id": "665f9e1a2b3c4d5e6f7a8b01",
    "title": "¿Cómo reciclo una botella de plást...",
    "updatedAt": "2024-06-05T10:22:00.000Z"
  },
  {
    "_id": "665f9e1a2b3c4d5e6f7a8b02",
    "title": "Análisis de imagen",
    "updatedAt": "2024-06-04T18:45:00.000Z"
  }
]

​
GET /api/ai/chats/:id

Retrieves the full message history of a single chat, including every user and bot turn, plus any attached image data. Authentication: Required. Path parameter
​
id
string
required
The _id of the chat to retrieve.
Response — the full Chat document from MongoDB:
​
_id
string
​
userId
string
The owner’s user _id.
​
title
string
​
mensajes
array
Ordered array of message objects.
​
mensajes[].role
string
"user" or "bot".
​
mensajes[].content
string
Text content of the message.
​
mensajes[].imagen
string
Base64 data URL of an attached image (present only on image-analysis messages).
​
updatedAt
string
​
createdAt
string
curl -X GET https://api.eco-it.app/api/ai/chats/665f9e1a2b3c4d5e6f7a8b01 \
  -H "Authorization: Bearer <token>"

{
  "_id": "665f9e1a2b3c4d5e6f7a8b01",
  "userId": "665f1a2b3c4d5e6f7a8b9c0d",
  "title": "¿Cómo reciclo una botella de plást...",
  "mensajes": [
    {
      "role": "user",
      "content": "¿Cómo reciclo una botella de plástico en Bogotá?"
    },
    {
      "role": "bot",
      "content": "El plástico tipo 1 (PET) va en la caneca blanca. Asegúrate de enjuagarla y aplastarla antes de depositarla."
    }
  ],
  "createdAt": "2024-06-05T10:20:00.000Z",
  "updatedAt": "2024-06-05T10:22:00.000Z"
}

​
DELETE /api/ai/chats/:id

Permanently deletes a single chat and all its messages. Authentication: Required. Path parameter
​
id
string
required
The _id of the chat to delete.
Response
​
success
boolean
​
message
string
"Chat eliminado correctamente".
curl -X DELETE https://api.eco-it.app/api/ai/chats/665f9e1a2b3c4d5e6f7a8b01 \
  -H "Authorization: Bearer <token>"

{ "success": true, "message": "Chat eliminado correctamente" }

​
DELETE /api/ai/chats

Deletes all chats belonging to the authenticated user. Use this for a “clear history” feature. Authentication: Required. Request body: None. Response
​
success
boolean
​
message
string
"Todos los chats han sido eliminados".
curl -X DELETE https://api.eco-it.app/api/ai/chats \
  -H "Authorization: Bearer <token>"

{ "success": true, "message": "Todos los chats han sido eliminados" }

​
EcoBot behaviour notes

EcoBot is restricted to topics about recycling, waste classification, composting, circular economy, renewable energy, and environmental sustainability in a Colombian context. It always refers to Colombia’s three-colour bin system: White (aprovechables — plastics, glass, metals), Black (no aprovechables — soiled paper, diapers), Green (orgánicos — food waste).
EcoBot responds in plain text only — no Markdown, no bold, no headings. Render the response content directly in your UI without a Markdown parser.

​
Error reference

HTTP StatusCause
400Missing pregunta or imagen field
401Missing, expired, or invalid JWT
404chatId not found or does not belong to the authenticated user
500OpenRouter / Gemini API error; internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us