Chat API

La Chat API permite enviar preguntas y recibir respuestas generadas por la inteligencia artificial, completas con citas documentales y fuentes verificables.

Conversaciones

Listar conversaciones

GET /api/conversations

Query parameters:

Parametro	Tipo	Default	Descripcion
page	number	1	Pagina actual
limit	number	20	Resultados por pagina
topicId	string	-	Filtra por categoria
search	string	-	Busqueda en el titulo

Ejemplo:

curl -X GET "https://api.queria.pro/api/conversations?page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Respuesta:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "conv_7f2a9b3c",
        "title": "Analisis contrato suministro",
        "topicId": "topic_456",
        "messageCount": 12,
        "lastMessageAt": "2026-03-04T09:15:00Z",
        "createdAt": "2026-03-03T14:20:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 34, "totalPages": 4 }
  }
}

Crear conversacion

POST /api/conversations

{
  "title": "Nuevo analisis",
  "topicId": "topic_456"
}

Respuesta:

{
  "success": true,
  "data": {
    "id": "conv_e4f5a6b7",
    "title": "Nuevo analisis",
    "topicId": "topic_456",
    "messages": []
  }
}

Detalle conversacion

GET /api/conversations/:id

Devuelve la conversacion con todos los mensajes, las fuentes asociadas y los metadatos.

Eliminar conversacion

DELETE /api/conversations/:id

Envio de mensajes

Mensaje no streaming

POST /api/chat/message

Request body:

{
  "message": "Cuales son las penalidades previstas en el contrato?",
  "conversationId": "conv_7f2a9b3c",
  "topicId": "topic_456",
  "enableExternalSources": true,
  "filters": {
    "documentType": ["pdf", "docx"],
    "dateRange": {
      "from": "2025-01-01",
      "to": "2025-12-31"
    },
    "topics": ["contratos", "legal"],
    "confidentiality": "internal"
  }
}

Campo	Tipo	Obligatorio	Descripcion
message	string	Si	Texto de la pregunta
conversationId	string	No	ID conversacion existente
topicId	string	No	Filtrar por categoria
enableExternalSources	boolean	No	Habilitar busqueda en bases de datos externas
filters	object	No	Filtros contextuales para la busqueda

Respuesta: (estructura identica a la version inglesa, con valores adaptados)

{
  "success": true,
  "data": {
    "messageId": "msg_c3d4e5f6",
    "response": "Las penalidades previstas en el contrato estan reguladas por el Art. 12 [1]. En particular, el proveedor esta sujeto a una penalidad del 2% por cada dia de retraso [2], hasta un maximo del 15% del valor total.",
    "sources": [
      {
        "id": "src_001",
        "documentId": "doc_8f3a2b",
        "documentName": "Contrato Suministro 2025.pdf",
        "content": "Art. 12 - Penalidades. El proveedor estara sujeto...",
        "score": 0.94,
        "sourceType": "document",
        "page": 8
      }
    ],
    "citationMap": {
      "1": { "sourceId": "src_001", "documentId": "doc_8f3a2b", "page": 8 }
    },
    "reasoningMetadata": {
      "strategy": "sequential",
      "steps": [
        { "type": "query_analysis", "duration": 120 },
        { "type": "document_retrieval", "duration": 340, "resultsFound": 7 },
        { "type": "reranking", "duration": 180, "resultsKept": 3 },
        { "type": "generation", "duration": 1200 }
      ],
      "totalDuration": 1840,
      "confidence": 0.91
    },
    "suggestions": [
      "Cual es el tope maximo de las penalidades?",
      "Existen clausulas de fuerza mayor?",
      "Como se calcula el retraso en la entrega?"
    ]
  }
}

Mensaje streaming (SSE)

POST /api/chat/stream

El body de la peticion es identico al endpoint no streaming. La cabecera Accept: text/event-stream activa el streaming.

curl -X POST https://api.queria.pro/api/chat/stream \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"conversationId": "conv_7f2a9b3c", "message": "Resume el contrato"}'

Eventos SSE:

data: {"type":"reasoning","step":"query_analysis","message":"Analisis de la pregunta..."}

data: {"type":"token","content":"Las penalidades"}

data: {"type":"token","content":" previstas en el contrato"}

data: {"type":"sources","sources":[{"id":"src_001","documentName":"Contrato Suministro 2025.pdf","score":0.94,"sourceType":"document"}]}

data: {"type":"done","citationMap":{"1":{"sourceId":"src_001","documentId":"doc_8f3a2b"}},"suggestions":["Cual es el tope maximo de las penalidades?"]}

Cliente JavaScript:

const response = await fetch('https://api.queria.pro/api/chat/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'qk_live_abc123def456ghi789jkl012',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({
    message: 'Cuales son las penalidades del contrato?',
    conversationId: 'conv_7f2a9b3c'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

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

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const event = JSON.parse(line.slice(6));

    switch (event.type) {
      case 'token':
        appendToResponse(event.content);
        break;
      case 'sources':
        displaySources(event.sources);
        break;
      case 'reasoning':
        updateReasoningPanel(event.step, event.message);
        break;
      case 'done':
        finalize(event.citationMap, event.suggestions);
        break;
    }
  }
}

Documentos temporales

Sube documentos temporales para analizarlos en una sola sesion de chat. Los archivos se eliminan automaticamente al final de la conversacion.

Upload documento temporal

POST /api/chat/upload-temp
Content-Type: multipart/form-data

Campo	Tipo	Descripcion
file	File	Documento a analizar
conversationId	string	ID conversacion de destino

Respuesta:

{
  "success": true,
  "data": {
    "tempDocId": "tmp_d4e5f6",
    "filename": "informe.pdf",
    "status": "PROCESSING"
  }
}

Estado de procesamiento

GET /api/chat/temp-doc/:id/status

{
  "success": true,
  "data": {
    "id": "tmp_d4e5f6",
    "status": "VECTORIZED",
    "progress": 100,
    "chunksCreated": 24
  }
}

Estados posibles: PROCESSING, VECTORIZED, ERROR.

Feedback

Permite a los usuarios valorar la calidad de las respuestas para mejora continua.

POST /api/chat/feedback

{
  "messageId": "msg_c3d4e5f6",
  "rating": "positive",
  "comment": "Respuesta precisa y bien documentada"
}

El campo rating acepta: positive, negative.

Endpoints publicos (Widget)

Endpoints accesibles mediante API Key, disenados para widgets e integraciones externas.

Metodo	Endpoint	Descripcion
POST	/api/public/chat/stream	Chat streaming con API Key
POST	/api/public/chat	Chat no streaming con API Key
GET	/api/public/topics	Lista categorias disponibles

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Cual es la politica de vacaciones?",
    "sessionId": "session_abc123",
    "topicId": "topic_456"
  }'

Estos endpoints respetan las restricciones de dominio configuradas para la API Key.

Errores comunes

Codigo	Error	Descripcion
400	INVALID_CONVERSATION	Conversacion no encontrada o acceso denegado
429	RATE_LIMITED	Demasiadas peticiones, esperar antes de reintentar
503	AI_UNAVAILABLE	Servicio IA temporalmente no disponible

Best practice

• Usa el streaming para una experiencia de usuario mejor y mas reactiva
• Implementa el debouncing en los inputs para evitar peticiones excesivas
• Gestiona los timeouts (maximo 60 segundos por respuesta)
• Implementa el retry con backoff exponencial para errores transitorios
• Visualiza las fuentes para transparencia y verificacion de la informacion
• Recoge el feedback de los usuarios para la mejora continua