RAGs

Un RAG es un conjunto de documentos indexados sobre el que se busca por significado. Estos endpoints te dejan consultarlo directamente desde tu backend, sin pasar por una inferencia ni por un agente.

Es la vía cuando quieres los fragmentos relevantes y el LLM lo pones tú, o cuando lo que necesitas es una búsqueda semántica dentro de tu producto.

Listar tus RAGs

curl https://ur.tuempresa.com/api/rags \
  -H "Authorization: Bearer $UR_TOKEN"

[
  {
    "id": "6f1c...",
    "name": "Documentación de ventas",
    "identifier": "ventas-docs",
    "status": "active",
    "totalFiles": 128,
    "processedFiles": 126,
    "numberVectors": 4821,
    "fileSource": {
      "id": "9a22...",
      "name": "Drive de ventas",
      "identifier": "drive-ventas",
      "provider": "google_drive"
    }
  }
]

totalFiles frente a processedFiles es el indicador rápido de salud: si difieren mucho, hay ficheros sin indexar — mira status y los ficheros para ver por qué.

Buscar en un RAG

curl -X POST https://ur.tuempresa.com/api/rags/ventas-docs/retrieve \
  -H "Authorization: Bearer $UR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"semanticSearch": ["plazo de devolución"], "topK": 10}'

{
  "chunks": [
    { "text": "El plazo de devolución es de 30 días naturales...", "score": 0.87 }
  ]
}

Cuerpo

Campo	Tipo	Por defecto	Descripción
semanticSearch	string[]	—	Obligatorio, de 1 a 10 queries
topK	int 1–100	5	Fragmentos a devolver
useReranking	bool	false	Reordena, si el RAG tiene reranker
candidateMultiplier	int 2–10	2	Candidatos antes de reordenar
similarityThreshold	number 0–1	—	Descarta por debajo de este parecido
includeDuplicates	bool	false	Incluye fragmentos marcados como duplicados
useAllFiles	bool	true	A false, restringe a lo seleccionado
selectedFiles	string[]	—	Rutas de fichero
selectedFolders	string[]	—	Rutas de carpeta

Aquí semanticSearch es obligatorio siempre

A diferencia de inferencias, donde solo hace falta si hay RAGs vinculados, aquí es el único sitio de donde sale la búsqueda: sin él es 400.

Y ojo con selectedFiles: aquí es una lista plana de rutas (["a.pdf", "b.pdf"]), no la forma por RAG que usan las inferencias. Es el mismo nombre con distinta forma porque aquí el RAG ya viene en la URL.

Igual que en inferencias, la búsqueda nunca lanza error: si algo se degrada, la respuesta incluye degraded.

Estado de un RAG

curl https://ur.tuempresa.com/api/rags/ventas-docs \
  -H "Authorization: Bearer $UR_TOKEN"

{
  "id": "6f1c...",
  "name": "Documentación de ventas",
  "identifier": "ventas-docs",
  "status": "active",
  "fileSourceScopeMode": "scoped",
  "fileSourceScopes": [{ "type": "path", "value": "documentos/" }],
  "totalFiles": 128,
  "processedFiles": 126,
  "numberVectors": 4821
}

Listar los ficheros

curl "https://ur.tuempresa.com/api/rags/ventas-docs/files?page=1&limit=50" \
  -H "Authorization: Bearer $UR_TOKEN"

page cambia la forma de la respuesta

Con page devuelve { data, total, page, limit }. Sin page devuelve el array completo, por compatibilidad con integraciones antiguas.

Usa siempre page en código nuevo: un RAG que crece puede devolver miles de filas de golpe.

limit va de 1 a 100, y por defecto es 20.

Acotar qué se indexa

Un RAG puede estar en dos modos:

• global — indexa todo lo que haya en su file source.
• scoped — indexa solo las rutas que le digas.

En modo scoped, estos dos endpoints gestionan esa lista desde tu código (útil si quien decide qué documentos entran es tu aplicación, no una persona en el panel):

# Añadir
curl -X POST https://ur.tuempresa.com/api/rags/ventas-docs/scopes \
  -H "Authorization: Bearer $UR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "path", "value": "documentos/"}'

# Quitar
curl -X DELETE https://ur.tuempresa.com/api/rags/ventas-docs/scopes \
  -H "Authorization: Bearer $UR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "path", "value": "documentos/"}'

Los dos devuelven {"ok": true}.

Formato del valor

Qué	type	value
Carpeta	path	Termina en / — "documentos/"
Fichero	path	Sin barra final — "documentos/informe.pdf"
Google Drive	externalId	El id del fichero o carpeta en Drive

La barra final no es cosmética

"documentos/" es una carpeta e incluye todo lo que cuelga de ella. "documentos" sin barra es un fichero llamado así. Si un scope no surte efecto, empieza por ahí.

Errores propios

Código	Cuándo
409	Ese scope ya estaba en la lista
422	El RAG está en modo global: no tiene lista que gestionar

Un 422 significa que primero hay que pasar el RAG a modo scoped en el panel.