POST/api/rag/{espacio}/conversations

Haz una pregunta a tu espacio

Bentho busca en los documentos del espacio y contesta solo con lo que dicen. Cada respuesta trae sus fuentes y cuánto confía en ella. Si reusas el session_id, entiende las preguntas de seguimiento.

PERMISOlee (vale cualquier clave)
CRÉDITOSgasta créditos
AUTENTICACIÓNBearer bth_…

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies).

CUERPO · JSON

CAMPO	TIPO	REQUERIDO	QUÉ ES
question	string	SÍ	La pregunta, en texto libre.
session_id	string	SÍ, EN LA PRÁCTICA	Tu identificador de conversación. Es obligatorio: sin él responde 400. Reúsalo para seguir el hilo; dos claves del mismo dueño con el mismo `session_id` comparten conversación.
history	[{ role: "user" \| "assistant", content }]	no	Turnos previos, si prefieres mandar tú el contexto. Sin él, se usa el historial de la sesión.

RESPUESTA 200

CAMPO	TIPO	QUÉ ES
status_code	"1000" \| "1001"	"1000" contesta con apoyo en los documentos. "1001" no hay información suficiente o prefiere no responder; `response` trae entonces el mensaje de rechazo del espacio.
response	string	El texto de la respuesta. Si hay fuentes, termina con el pie «Referencia: …».
sources	string[]	Los documentos citados. Vacío con 1001.
confidence	number \| null	De 0 a 1. Desde 0,75 responde; entre 0,55 y 0,75 responde con warning; por debajo, 1001.
warning	boolean	true si solo parte de la respuesta está respaldada. Sigue siendo 1000.
claim_attributions	array \| null	Por frase: { sentence, chunk_index, entailment, supported }.
session_id	string \| null	El que mandaste.
tenant_id · query	string	El espacio y la pregunta original.
verification · condensed_query	object \| null · string \| null	Detalle de la verificación y la pregunta reescrita, si la hubo.

ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}

STATUS	CUÁNDO	DETAIL LITERAL
400	Falta session_id	session_id es obligatorio.
402	La cuenta agotó sus créditos del ciclo	La cuenta de este espacio agotó sus créditos de este ciclo.
404	El espacio no existe	—
422	Falta question	—
502	El servicio no respondió a tiempo: reintenta con espera creciente	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

CONVIENE SABER

Un error interno al responder no llega como 5xx: llega como 200 con status_code: "1001" y el texto «Ocurrió un error interno procesando la consulta. Intenta de nuevo.». Trátalo como una respuesta sin información.
Una consulta típica tarda de 2 a 20 s. Pon el timeout de tu cliente en 60 s o más.
En espacios con el módulo de Ventas la respuesta tiene otra forma (estado, cotizacion, handoff…) y no usa history.