ClaixClaixES

Claix Retrieve

Call an agent

Ask a Retrieve agent questions against your connected database with your API key.

Claix Retrieve

Call an agent

Endpoint

POSThttps://claix.dev/retrieve/{agent_name}

A Retrieve agent is the entry point you connect to your app or assistant. The URL carries the agent name (the slug from when you created it). With your API key, Claix knows who is asking, which routes are allowed, and how to shape the answer.

For each question the agent picks a route, builds a read-only query over the allowed tables and columns, runs it on your connected database, and returns either raw rows or a typed value—depending on the agent's response mode.

Public URL: POST https://claix.dev/retrieve/{agent_name}. Never expose the raw Supabase function URL.

1. Authentication

Every request must include your API key.

Option A — Dedicated header (recommended):

x-api-key: <YOUR_API_KEY>

Option B — Standard Authorization header:

Authorization: Bearer <YOUR_API_KEY>

The key must exist and be active, and the account must not be suspended. Failures return 401.

2. Agent URL

The last path segment is the agent name (slug), e.g. agenteextractor. We also accept the display name when it is unique in your account; if several match, use the slug from the dashboard URL.

POST https://claix.dev/retrieve/{agent_name}
  • The agent must be active (not paused).
  • It needs at least one active route with a published definition on the same connection as the agent.

3. Request body

Method: POST · Content-Type: application/json

FieldTypeRequiredDescription
questionsarray of { question, format }YesUp to 5 questions. question: text ≤400 characters. format: response typing (only required when the agent is in reasoned mode).
{
  "questions": [
    { "question": "How many orders are confirmed?", "format": "int" },
    { "question": "What is the name of the customer with the most orders?", "format": "string" }
  ]
}

Accepted format values (reasoned mode): string, int, boolean, timestamp, timestamptz, date, json, array:string, array:int. The alias timestampz is also accepted.

If the agent is in raw mode, format is ignored: each answer is the JSON rows as returned by the database.

4. Agent response mode

ModeWhat you get
raw (bruto)Per question: { rows, truncated }. rows is the query result. truncated means the row cap was hit.
reasoned (razonada)Per question: a single typed value matching format (or null if the data is missing or unsafe to type). The model only uses the rows; it does not invent facts.

You set the mode on the agent in the dashboard. It is not sent in the request.

5. Response

Success (reasoned mode):

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

Success (raw mode, one-question example):

{
  "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"
}
FieldDescription
user_askEcho of the questions you sent (and format if present).
ia_responseArray aligned with user_ask: typed value, { rows, truncated }, or { error: "…" } if that question failed.
log_idId of the call record (useful in Traces).

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

6. What Claix does per question

  1. Reads the question with the business prompt and the agent's routes.
  2. Proposes a route and a read-only query.
  3. Validates the query (single read statement, only tables and columns allowed on that route). Up to 3 attempts to change route or fix the query.
  4. Runs the query safely on your connected database.
  5. Returns rows (raw) or a typed value (reasoned).

7. Common error codes

CodeMeaning
401Missing/invalid API key or inactive account.
400Invalid body, format required in reasoned mode, or no usable routes on the agent.
404No agent with that name.
409Agent is paused, or several agents share the same display name.
502The model could not prepare the query.

Request examples

curl -X POST "https://claix.dev/retrieve/agenteextractor" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
    ]
  }'