ClaixClaixES

Claix Retrieve

Agent Actions

Create, edit, and pause or resume Retrieve agents via API.

Agents · Create

Create an agent via API

Endpoint

POSThttps://claix.dev/agents

Creates a Claix Retrieve agent on the API key account, with assigned routes and a response mode. It starts active and ready at /retrieve/{slug}.

This call is free.

1. Authentication

x-api-key: <YOUR_API_KEY>

or

Authorization: Bearer <YOUR_API_KEY>

2. Request format

Method: POST · Content-Type: application/json. Every field is required.

FieldTypeRequiredDescription
namestringYesVisible agent name (max 80).
slugstringYesURL id for /retrieve/{slug}. 3–20 chars: a-z and 0-9.
descriptionstringYesWhat the agent is for (max 500).
promptstringYesBusiness instructions (max 12,000).
routesuuid[]Yesroute_id list from your account. At least one.
response_modestringYes"bruto" (SQL rows) or "razonada" (typed answer).

3. How to build the call

  1. Create at least one route (POST /routes) and copy its route_id.
  2. Pick a slug unique in your account.
  3. POST to https://claix.dev/agents with every field.
  4. Save agent_id and use retrieve_url to ask questions.

4. Examples

Right panel: cURL, JavaScript, Node.js, Python, PHP, and n8n.

5. Successful response

201 Created

{
  "success": true,
  "agent": {
    "agent_id": "9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
    "name": "Asistente de agenda",
    "slug": "agenda",
    "description": "Responde preguntas sobre citas y pacientes de la clínica.",
    "status": "active",
    "prompt": "Eres el asistente de la clínica. Solo usas las rutas asignadas. No inventes datos.",
    "routes": ["7c2f9a1e-4b8d-4e6a-9f21-0a1b2c3d4e5f"],
    "response_mode": "razonada",
    "retrieve_url": "https://claix.dev/retrieve/agenda",
    "created_at": "2026-10-19T18:00:00.000Z"
  }
}

6. Errors

HTTPWhen
401Invalid API key or inactive account.
400Missing field, invalid/duplicate slug, or a route is not yours.
405Method other than POST.
500Internal 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"
}

Request examples

curl -X POST "https://claix.dev/agents" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{  "name": "Asistente de agenda",  "slug": "agenda",  "description": "Responde preguntas sobre citas y pacientes de la clínica.",  "prompt": "Eres el asistente de la clínica. Solo usas las rutas asignadas. No inventes datos.",  "routes": [    "7c2f9a1e-4b8d-4e6a-9f21-0a1b2c3d4e5f"  ],  "response_mode": "razonada"}'