Vision General API

La REST API de Queria permite integrar las funcionalidades de busqueda documental inteligente, chat IA y gestion de documentos dentro de cualquier aplicacion.

Base URL

Todas las peticiones API usan la siguiente base URL:

https://api.queria.pro

La API sigue el versionado via path. La version actual es v3.5.0. Los endpoints publicos son accesibles bajo /api/public/, los autenticados bajo /api/.

Formato de las respuestas

Todas las respuestas son en formato JSON con estructura consistente.

Respuesta exitosa:

{
  "success": true,
  "data": {
    "id": "doc_8f3a2b1c",
    "name": "Contrato Suministro 2025",
    "status": "VECTORIZED",
    "createdAt": "2026-02-15T10:30:00Z"
  }
}

Respuesta paginada:

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8
    }
  }
}

Respuesta de error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo 'message' es obligatorio.",
    "details": [
      { "field": "message", "reason": "Campo requerido" }
    ]
  }
}

Codigos de estado HTTP

Codigo	Significado	Descripcion
200	OK	Peticion completada con exito
201	Created	Recurso creado con exito
400	Bad Request	Parametros faltantes o no validos
401	Unauthorized	Autenticacion faltante o no valida
403	Forbidden	Permisos insuficientes para la operacion
404	Not Found	Recurso no encontrado
429	Too Many Requests	Limite de peticiones superado
500	Internal Server Error	Error interno del servidor

Rate limiting

La API aplica limites de frecuencia para garantizar estabilidad y rendimiento.

Tipo de endpoint	Limite	Ventana
Endpoints publicos	60 peticiones	1 minuto
Endpoints autenticados	300 peticiones	1 minuto
Upload documentos	10 peticiones	1 minuto
Chat streaming	20 peticiones	1 minuto

Las respuestas incluyen cabeceras informativas sobre el rate limit:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709542800

Cuando se supera el limite, la API devuelve un error 429:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de peticiones superado. Reintenta en 23 segundos.",
    "retryAfter": 23
  }
}

Content-Type

Todas las peticiones JSON deben incluir la cabecera:

Content-Type: application/json

Para los uploads de archivo, usa:

Content-Type: multipart/form-data

Autenticacion

La API soporta dos metodos de autenticacion:

• JWT Token: para sesiones de usuario en aplicaciones web. Incluido via cabecera Authorization: Bearer {token}.
• API Key: para integraciones server-to-server y widgets. Incluida via cabecera X-API-Key.

Las API Key siguen el formato qk_live_* para produccion y qk_test_* para entornos de test.

Para los detalles completos consulta la guia de autenticacion.

Ejemplo rapido

Una llamada tipica a la chat API con autenticacion via API Key:

curl -X POST https://api.queria.pro/api/public/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qk_live_abc123def456ghi789" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Cuales son las clausulas principales del contrato?",
    "sessionId": "sess_a1b2c3d4"
  }'

Respuesta streaming (Server-Sent Events):

data: {"type":"token","content":"Las clausulas"}
data: {"type":"token","content":" principales del contrato"}
data: {"type":"token","content":" son las siguientes [1]:"}
data: {"type":"sources","sources":[{"id":"doc_8f3a","name":"Contrato Suministro","score":0.92}]}
data: {"type":"done","citationMap":{"1":{"documentId":"doc_8f3a","chunkId":"chk_001"}}}

Endpoints principales

Autenticacion

Metodo	Endpoint	Descripcion
POST	/api/auth/login	Login usuario
POST	/api/auth/register	Registro
POST	/api/auth/refresh	Refresh token
POST	/api/auth/logout	Logout

Chat

Metodo	Endpoint	Descripcion
GET	/api/conversations	Lista conversaciones
POST	/api/conversations	Nueva conversacion
POST	/api/chat/message	Envia mensaje
POST	/api/chat/stream	Chat streaming

Documentos

Metodo	Endpoint	Descripcion
GET	/api/documents	Lista documentos
POST	/api/documents/upload	Upload documento
GET	/api/documents/:id	Detalle documento
PUT	/api/documents/:id	Actualiza documento
DELETE	/api/documents/:id	Elimina documento

Topics

Metodo	Endpoint	Descripcion
GET	/api/topics	Lista categorias
POST	/api/topics	Crea categoria
PUT	/api/topics/:id	Actualiza categoria
DELETE	/api/topics/:id	Elimina categoria

Empresas

Metodo	Endpoint	Descripcion
GET	/api/companies	Lista empresas
GET	/api/companies/:id	Detalle empresa
PUT	/api/companies/:id	Actualiza empresa

API Publicas (Widget)

Metodo	Endpoint	Descripcion
POST	/api/public/chat	Chat no streaming
POST	/api/public/chat/stream	Chat streaming SSE
POST	/api/public/search/web	Busqueda web
GET	/api/public/topics	Lista categorias

Paginacion

Query parameters estandar para las listas:

Parametro	Default	Descripcion
page	1	Numero de pagina
limit	20	Elementos por pagina (max 100)
sort	createdAt	Campo de ordenacion
order	desc	Direccion: asc o desc

Ejemplo:

curl -X GET "https://api.queria.pro/api/documents?page=2&limit=50&sort=name&order=asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Webhook (Coming Soon)

Notificaciones para eventos asincronos:

• document.uploaded - Documento subido
• document.vectorized - Procesamiento completado
• document.error - Error de procesamiento
• conversation.created - Nueva conversacion

SDK

SDK oficiales en desarrollo:

• JavaScript / TypeScript
• Python
• PHP

Mientras tanto, usa la REST API directamente con cualquier cliente HTTP.

Proximos pasos

• Autenticacion - Configurar JWT y API Key
• Chat API - Enviar mensajes y recibir respuestas IA
• Documentos API - Subir y gestionar documentos
• Integraciones - Incrustar Queria en tu aplicacion