ClaixClaixEN

Claix Retrieve

Routes Actions

Crea, edita y elimina rutas de Retrieve por API. Las tablas y columnas deben coincidir con tu Data Map publicado.

Rutas · Crear

Crear una ruta por API

Endpoint

POSThttps://claix.dev/routes

Crea una ruta de Claix Retrieve en la cuenta de la API key: registra la ruta y su primera versión con tablas, columnas y reglas. Las tablas y columnas deben existir en el Data Map publicado de tu conexión activa.

Llama siempre a https://claix.dev/routes.

Pensado para integraciones server-to-server. Esta llamada es gratuita: no se factura.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor, distinta de cualquier token de sesión.

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.

El sistema valida que la key exista, esté activa y la cuenta no esté suspendida. Si falla, responde 401.

2. Requisitos previos

  1. Tener una conexión a base de datos activa en el dashboard.
  2. Tener un Data Map publicado para esa conexión, con las tablas y columnas que vas a autorizar en la ruta.
  3. Conocer los nombres exactos de tablas y columnas tal como aparecen en el Data Map.

3. Formato de la petición

Método: POST · Content-Type: application/json

Todos los campos del cuerpo son obligatorios. Si falta alguno, la respuesta 400 indica exactamente qué parámetro falta.

CampoTipoObligatorioDescripción
namestringSíNombre visible de la ruta (1–80 caracteres). Se usa para generar el slug.
descriptionstringSíCuándo debe usar el agente esta ruta (10–300 caracteres).
rulesstringSíInstrucciones y restricciones de la ruta (máx. 20.000 caracteres).
tablesarraySíTablas y columnas autorizadas. Al menos una tabla con al menos una columna.

Cada elemento de tables debe ser:

{
  "name": "appointments",
  "columns": ["id", "patient_id", "starts_at", "status"]
}
  • name: nombre de la tabla en el Data Map.
  • columns: array de nombres de columna (strings). Claix completa tipos y metadatos desde el Data Map.

4. Cómo construir la llamada

  1. Ten a mano tu API key.
  2. Elige tablas y columnas que existan en tu Data Map publicado.
  3. Construye un POST JSON a https://claix.dev/routes con name, description, rules y tables.
  4. Añade el header de autenticación y comprueba el código HTTP: 201 indica que se creó.

5. Ejemplos de llamada

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.

6. Formato de la respuesta exitosa

201 Created · Content-Type: application/json

{
  "success": true,
  "route": {
    "route_id": "7c2f9a1e-4b8d-4e6a-9f21-0a1b2c3d4e5f",
    "name": "Agenda de citas",
    "slug": "agenda_de_citas",
    "description": "Consulta la agenda de la clínica: pacientes, horarios y estado de la cita.",
    "status": "draft",
    "created_at": "2026-10-19T17:00:00.000Z",
    "version": {
      "version_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "version": 1,
      "status": "draft",
      "rules": "Solo SELECT. Filtra por clínica del usuario. No expongas teléfonos ni emails.",
      "definition": {
        "schema_version": 1,
        "tables": [
          {
            "name": "appointments",
            "description": "Citas de la clínica",
            "columns": [
              {
                "name": "id",
                "type": "uuid",
                "nullable": false,
                "is_primary_key": true,
                "description": "Identificador de la cita",
                "sensitivity_hint": "none"
              }
            ]
          }
        ]
      },
      "validation": {
        "valid": true,
        "errors": [],
        "warnings": [],
        "validated_at": "2026-10-19T17:00:00.000Z"
      }
    }
  },
  "warnings": []
}

Guarda el route_id para editar o borrar la ruta, y para asignarla a un agente en el dashboard. La versión se crea en estado draft; publícala desde el panel cuando quieras usarla en producción.

7. Errores frecuentes

HTTPCuándo
401Falta la API key, es inválida o la cuenta no está activa.
400Falta un parámetro obligatorio, o alguna tabla/columna no está en el Data Map, o no hay conexión / Data Map publicado.
405Método distinto de POST.
500Error interno al guardar la ruta o su versión.

Ejemplo de error:

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Si fallan tablas o columnas, el cuerpo puede incluir details con la lista de incidencias (tabla o columna concreta).

Ejemplos de petición

curl -X POST "https://claix.dev/routes" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{  "name": "Agenda de citas",  "description": "Consulta la agenda de la clínica: pacientes, horarios y estado de la cita.",  "rules": "Solo SELECT. Filtra por clínica del usuario. No expongas teléfonos ni emails.",  "tables": [    {      "name": "appointments",      "columns": ["id", "patient_id", "starts_at", "status"]    },    {      "name": "patients",      "columns": ["id", "full_name"]    }  ]}'