API HTTP

La API para llamar a ur desde tu backend: ejecutar inferencias, buscar en tus RAGs y consultar el estado de indexación de tus documentos.

Recurso	Para qué
Inferencias	Ejecutar un prompt, con o sin tus documentos como contexto
RAGs	Buscar fragmentos relevantes, listar ficheros, acotar el alcance
Webhooks	Que otros sistemas avisen a ur de que hay cambios
Agentes	Un turno de agente sin streaming

Base URL y autenticación

Todo cuelga de /api en el origen de tu instancia, y va con un access token en la cabecera Authorization:

curl https://ur.tuempresa.com/api/inferences \
  -H "Authorization: Bearer ur-Ah7kQ2mZ..."

No hay CORS

Esta API no se llama desde un navegador

/api/* no emite cabeceras CORS, a propósito: el token Bearer no debe llegar nunca a un navegador, porque cualquiera que abra las devtools se lo lleva.

Llámala solo desde tu servidor. Si lo que necesitas es hablar desde el navegador del usuario final, la vía es el canal de agentes, que está diseñado para ser público.

Permisos

El token declara sobre qué recursos puede actuar, en tres grupos: agents, inferences y rags. Ver Credenciales.

Hay dos comportamientos distintos según cómo llegues al recurso:

• Listados — filtran en silencio. GET /api/inferences devuelve solo las permitidas.
• Acceso directo — 403 {"error":"Forbidden"} si el recurso existe pero no está permitido.

Errores

Código	Cuerpo	Cuándo
400	{"error":"..."}	Cuerpo inválido. El mensaje enumera los campos que fallan
401	{"error":"Unauthorized"}	Falta el token o no existe
403	{"error":"Forbidden"}	El token no cubre ese recurso
404	{"error":"Not found"}	No existe ese identifier
429	{"error":"Too many requests"}	Superado el límite
502	{"error":"..."}	Falló el proveedor del modelo
503	{"error":"Rate limiting unavailable"}	El backend no puede hablar con Redis

Límites de peticiones

Por IP y ventana de 60 segundos:

Superficie	Límite
/api/inferences, /api/agents, /api/rags	60 por minuto
/api/webhooks/*	20 por minuto
/embed/*	30 por minuto

El límite se comprueba antes que la autenticación, así que un token inválido también consume cuota.

El 503 es a propósito

Si Redis no está disponible, las rutas con límite devuelven 503 en vez de dejar pasar el tráfico. Falla cerrado. Un 503 aquí apunta a la infraestructura, no a tu petición.

Campos solo de administrador

La API acepta también la cookie de sesión del panel, y esto tiene una consecuencia que muerde al pasar a producción:

Probar en el navegador enseña campos que luego no están

Con sesión de administrador la respuesta trae campos de diagnóstico que con un token Bearer no aparecen:

• timings — desglose de tiempos (contexto, reranking, LLM)
• usage — tokens consumidos y coste
• toolCalls[].debug — detalle interno de cada tool
• message dentro de degraded
• la cabecera X-Inference-Timings

Si construyes tu integración probando desde el navegador con sesión abierta y luego cambias a un token, esos campos desaparecen sin previo aviso. No los des por hechos.

Referencia navegable

Tu propia instancia publica la especificación OpenAPI, generada del código y siempre al día:

URL	Qué es
https://<tu-instancia>/api/docs	Referencia navegable, campo a campo
https://<tu-instancia>/api/openapi.json	La especificación en crudo, para generar clientes

Las dos son públicas: no hacen falta credenciales para leerlas (sí para llamar a los endpoints).

Dos cosas no están en la especificación

Los endpoints de agente por HTTP (GET /api/agents/{identifier} y POST /api/agents/{identifier}/invoke) y los webhooks no aparecen en el OpenAPI. Su documentación es la de este sitio.