ClaixClaixES

Claix Retrieve

Routes Actions

Create, edit, and delete Retrieve routes via API. Tables and columns must match your published Data Map.

Routes · Create

Create a route via API

Endpoint

POSThttps://claix.dev/routes

Creates a Claix Retrieve route on the API key account: stores the route and its first version with tables, columns, and rules. Tables and columns must exist in the published Data Map of your active connection.

Always call https://claix.dev/routes.

Intended for server-to-server integrations. This call is free: it is not billed.

1. Authentication

Every request must include your API key. It is a personal server credential, distinct 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.

The system checks that the key exists, is active, and the account is not suspended. On failure it returns 401.

2. Prerequisites

  1. An active database connection in the dashboard.
  2. A published Data Map for that connection, including the tables and columns you will authorize on the route.
  3. Exact table and column names as they appear in the Data Map.

3. Request format

Method: POST · Content-Type: application/json

Every body field is required. If one is missing, the 400 response names the missing parameter.

FieldTypeRequiredDescription
namestringYesVisible route name (1–80 chars). Used to generate the slug.
descriptionstringYesWhen the agent should use this route (10–300 chars).
rulesstringYesInstructions and restrictions for the route (max 20,000 chars).
tablesarrayYesAuthorized tables and columns. At least one table with one column.

Each item in tables must look like:

{
  "name": "appointments",
  "columns": ["id", "patient_id", "starts_at", "status"]
}
  • name: table name in the Data Map.
  • columns: array of column name strings. Claix fills types and metadata from the Data Map.

4. How to build the call

  1. Have your API key ready.
  2. Pick tables and columns that exist in your published Data Map.
  3. Build a JSON POST to https://claix.dev/routes with name, description, rules, and tables.
  4. Add the auth header and check the status: 201 means it was created.

5. Call examples

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

6. Successful response

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": []
}

Save route_id to edit or delete the route, and to assign it to an agent in the dashboard. The version is created as draft; publish it from the panel when you want it in production.

7. Common errors

HTTPWhen
401Missing/invalid API key or inactive account.
400Missing required field, table/column not in the Data Map, or no active connection / published Data Map.
405Method other than POST.
500Internal error while saving the route or its version.

Error example:

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

When tables or columns fail, the body may include details listing each issue.

Request examples

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"]    }  ]}'