Claix Retrieve
Llamar a un agente
Endpoint
https://claix.dev/retrieve/{agent_name}Un agente de Retrieve es el punto de entrada que conectas a tu aplicación o a tu asistente. En la URL va el nombre del agente (el slug que viste al crearlo). Con tu API key, Claix sabe quién pregunta, qué rutas puede usar y cómo debe devolver la respuesta.
Por cada pregunta el agente elige una ruta, genera una consulta de solo lectura sobre las tablas y columnas permitidas, la ejecuta en tu base de datos y te devuelve el resultado en bruto o tipado, según el modo del agente.
URL pública: POST https://claix.dev/retrieve/{agent_name}. Nunca expongas la URL directa de Supabase.
1. Autenticación
Toda petición debe incluir tu API key.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
La key debe existir y estar activa, y la cuenta no puede estar suspendida. Si falla, responde 401.
2. URL del agente
El segmento final es el nombre del agente (slug), por ejemplo agenteextractor. También aceptamos el nombre visible si es único en tu cuenta; si hay varios, usa el slug de la URL del panel.
POST https://claix.dev/retrieve/{nombre_del_agente}- El agente debe estar activo (no en pausa).
- Debe tener al menos una ruta activa con definición publicada y la misma conexión que el agente.
3. Cuerpo de la petición
Método: POST · Content-Type: application/json
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| questions | array de { question, format } | Sí | Hasta 5 preguntas. question: texto ≤400 caracteres. format: tipado de la respuesta (solo si el agente está en modo razonada). |
{
"questions": [
{ "question": "¿Cuántos pedidos hay en estado confirmado?", "format": "int" },
{ "question": "¿Cuál es el nombre del cliente con más pedidos?", "format": "string" }
]
}format aceptados (modo razonada): string, int, boolean, timestamp, timestamptz, date, json, array:string, array:int. También se admite el alias timestampz.
Si el agente está en modo bruto, format se ignora: la respuesta de cada pregunta es el JSON de filas tal cual salió de la base.
4. Modo de respuesta del agente
| Modo | Qué recibes |
|---|---|
| bruto | Por pregunta: { rows, truncated }. Las filas son el resultado de la consulta. truncated indica si se cortó el tope de filas. |
| razonada | Por pregunta: un único valor tipado según format (o null si no hay dato fiable). El modelo interpreta las filas; no inventa datos que no estén en ellas. |
El modo lo configuras en el panel del agente. No se envía en la petición.
5. Respuesta
Éxito (modo razonada):
{
"user_ask": [
{ "question": "¿Cuántos pedidos hay en estado confirmado?", "format": "int" },
{ "question": "¿Cuál es el nombre del cliente con más pedidos?", "format": "string" }
],
"ia_response": [42, "Acme Corp"],
"log_id": "7c2f9a10-4b8e-4d1a-9f33-1e6a0c8d2b55"
}Éxito (modo bruto, ejemplo de una pregunta):
{
"user_ask": [
{ "question": "¿Cuántos pedidos hay en estado confirmado?", "format": null }
],
"ia_response": [
{
"rows": [{ "total": 42 }],
"truncated": false
}
],
"log_id": "7c2f9a10-4b8e-4d1a-9f33-1e6a0c8d2b55"
}| Campo | Descripción |
|---|---|
| user_ask | Eco de las preguntas enviadas (y format si venía). |
| ia_response | Array alineado con user_ask: valor tipado, objeto { rows, truncated }, o { error: "…" } si esa pregunta falló. |
| log_id | Identificador del registro de la llamada (útil para Traces). |
Error genérico:
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos).",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}6. Qué hace Claix por cada pregunta
- Analiza la pregunta junto al prompt de negocio y las rutas del agente.
- Propone una ruta y una consulta de solo lectura.
- Valida la consulta (única sentencia de lectura, tablas y columnas permitidas por esa ruta). Hasta 3 intentos si hace falta cambiar de ruta o corregir.
- Ejecuta la consulta de forma segura en tu base conectada.
- Devuelve filas (bruto) o un valor tipado (razonada).
7. Códigos de error frecuentes
| Código | Significado |
|---|---|
| 401 | API key ausente, inválida o cuenta inactiva. |
| 400 | Body inválido, format obligatorio en modo razonada, o el agente no tiene rutas utilizables. |
| 404 | No existe un agente con ese nombre. |
| 409 | El agente está en pausa, o hay varios con el mismo nombre visible. |
| 502 | No se pudo usar el modelo para preparar la consulta. |