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.

1. Tener una conexión a base de datos activa (PostgreSQL, MySQL o MariaDB).
2. Tener al menos un guard activo en esa conexión si quieres limitar escrituras. Sin guards activos, la escritura se permite.
3. Si la cuenta tiene varias conexiones activas, conocer el connection_id de la que quieres comprobar.

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

El cuerpo es un objeto JSON. Solo sql es obligatorio.

Ejemplo para PostgreSQL:

{
  "sql": "INSERT INTO shop.orders (customer_id, total) VALUES ($1, $2)",
  "params": ["c-1042", 6200],
  "connection_id": "8f14e45f-ceea-4e6f-8b23-1e2d3c4b5a6f"
}

En MySQL o MariaDB la misma sentencia usa ?: VALUES (?, ?). El cuerpo de la petición sigue siendo el mismo. El cuerpo completo puede medir hasta 1 MB.

• Las comparaciones de texto distinguen mayúsculas, acentos y espacios finales.
• Cualifica las tablas (esquema.tabla en PostgreSQL, base.tabla en MySQL). Un nombre que existe en más de un esquema se deniega.
• Una columna que un guard lee y el INSERT omite hace que la sentencia se deniegue.

1. Ten a mano tu API key y la sentencia que el agente propone.
2. Si el SQL usa marcadores, pon los valores en params en el mismo orden.
3. Si hay más de una conexión activa, añade su connection_id.
4. Haz un POST JSON a https://claix.dev/check-sql con el header de autenticación.
5. Un 200 es una comprobación terminada. Lee allowed: true la permite y false la deniega. El código y el motivo van en code y reason.

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

200 OK · Content-Type: application/json

El 200 cubre tanto el permiso como la denegación. La decisión está en allowed. El campo sql repite la sentencia comprobada, tal como se envió, en los dos casos. Si en Guard Traces hay un endpoint de aviso, Claix envía este mismo JSON con un POST a la URL de permitidos o a la de denegados.

Permiso:

{
  "allowed": true,
  "decision_id": "1a2b3c4d-5e6f-4789-a012-3456789abcde",
  "code": "allowed",
  "reason": "Ninguna regla prohíbe esta operación.",
  "operation": "insert",
  "table": "shop.orders",
  "sql": "INSERT INTO shop.orders (customer_id, total) VALUES ($1, $2)",
  "affected_rows": 1,
  "violations": [],
  "rules_checked": 1,
  "latency_ms": 840
}

Denegación:

{
  "allowed": false,
  "decision_id": "9ff38974-1392-4c1a-83e5-3b2f09bb43dc",
  "code": "rule_denied",
  "reason": "No se pueden crear pedidos con un total superior a 5000.",
  "operation": "insert",
  "table": "shop.orders",
  "sql": "INSERT INTO shop.orders (customer_id, total) VALUES ($1, $2)",
  "affected_rows": 1,
  "violations": [
    {
      "guard_id": "b7c1d2e3-4f56-4789-a012-3456789abcde",
      "guard_name": "Límite de total en pedidos",
      "rule_id": "e2a9c4b1-6d70-4e85-9f12-abcdef012345",
      "rule_title": "Total máximo",
      "code": "rule_denied",
      "message": "No se pueden crear pedidos con un total superior a 5000."
    }
  ],
  "rules_checked": 1,
  "latency_ms": 1104
}

Cada elemento de violations incluye:

Códigos de veredicto que llegan con HTTP 200:

Estos códigos HTTP son fallos de la llamada. Una denegación de la sentencia sigue siendo 200 con allowed: false.

Ejemplo de error:

{
  "error": "missing_sql",
  "message": "Falta \"sql\": la sentencia que el agente quiere ejecutar."
}