ClaixClaixEN

Claix Retrieve

Agent Actions

Crea, edita y pausa o reactiva agentes de Retrieve por API.

Agentes · Crear

Crear un agente por API

Endpoint

POSThttps://claix.dev/agents

Crea un agente de Claix Retrieve en la cuenta de la API key, con rutas asignadas y modo de respuesta. Queda active y listo para llamar en /retrieve/{slug}.

Esta llamada es gratuita.

1. Autenticación

x-api-key: <TU_API_KEY>

o

Authorization: Bearer <TU_API_KEY>

2. Formato de la petición

Método: POST · Content-Type: application/json. Todos los campos son obligatorios.

CampoTipoObligatorioDescripción
namestringSíNombre visible del agente (máx. 80).
slugstringSíIdentificador en la URL /retrieve/{slug}. 3–20 chars: a-z y 0-9.
descriptionstringSíPara qué sirve el agente (máx. 500).
promptstringSíInstrucciones de negocio del agente (máx. 12.000).
routesuuid[]SíLista de route_id de tu cuenta. Al menos uno.
response_modestringSí"bruto" (filas SQL) o "razonada" (respuesta tipada).

3. Cómo construir la llamada

  1. Crea al menos una ruta (POST /routes) y copia su route_id.
  2. Elige un slug único en tu cuenta.
  3. Envía POST a https://claix.dev/agents con todos los campos.
  4. Guarda agent_id y usa retrieve_url para preguntar.

4. Ejemplos

Panel derecho: cURL, JavaScript, Node.js, Python, PHP y n8n.

5. Respuesta exitosa

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. Errores

HTTPCuándo
401API key inválida o cuenta inactiva.
400Falta un parámetro, slug inválido/duplicado, o alguna ruta no es tuya.
405Método distinto de POST.
500Error interno.
{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Ejemplos de petición

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