Every request must include your API key. It is a server credential, separate from any session token.

Option A — dedicated header (recommended):

x-api-key: <YOUR_API_KEY>

Option B — standard Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Either one is enough. If you send both, x-api-key wins.

Claix checks that the key exists, is active, and the account is not suspended. A failure returns 401.

1. An active database connection (PostgreSQL, MySQL, or MariaDB).
2. At least one active guard on that connection if you want writes limited. With no active guards, the write is allowed.
3. If the account has more than one active connection, the connection_id of the one you want to check.

Method: POST · Content-Type: application/json

The body is a JSON object. Only sql is required.

PostgreSQL example:

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

On MySQL or MariaDB the same statement uses ?: VALUES (?, ?). The request body stays the same. The whole body can be up to 1 MB.

• Text comparisons distinguish case, accents, and trailing spaces.
• Qualify table names (schema.table on PostgreSQL, database.table on MySQL). A name that exists in more than one schema is denied.
• A column that a guard reads and the INSERT leaves out denies the statement.

1. Have your API key and the statement the agent proposes.
2. If the SQL uses placeholders, put the values in params in the same order.
3. If there is more than one active connection, add its connection_id.
4. POST JSON to https://claix.dev/check-sql with the authentication header.
5. A 200 means the check finished. Read allowed: true allows it and false denies it. The code and the reason are in code and reason.

See the panel on the right for cURL, JavaScript, Node.js, Python, PHP, and n8n examples.

200 OK · Content-Type: application/json

A 200 covers both an allow and a denial. The decision is in allowed. The sql field repeats the statement that was checked, as it was sent, in both cases. If Guard Traces has an alert endpoint, Claix POSTs this same JSON to the allowed URL or the denied URL.

Allowed:

{
  "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
}

Denied:

{
  "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
}

Each item in violations includes:

Verdict codes returned with HTTP 200:

These HTTP statuses are call failures. A denial of the statement is still 200 with allowed: false.

Error example:

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

The message field is returned in Spanish.