Skip to main content
Endpoint · GET /ai-employees
Endpoint de solo consulta: devuelve información y no modifica nada. No se manda dentro del array actions — se llama directo.
Devuelve los empleados AI ejecutables y activos del business, en orden alfabético y paginados por cursor. De aquí sale el name exacto que necesitan las acciones que reciben un empleado AI: la API los identifica por nombre, no por id, así que este catálogo es la forma de saber qué nombres existen antes de armar una acción. Cada elemento trae su type:
  • operative — puede asignarse a la conversación y también ejecutarse.
  • json — solo puede ejecutarse de forma puntual. Asignarlo con assign_ai_employee falla con AI_EMPLOYEE_NOT_FOUND.
El catálogo omite los empleados AI inactivos y los eliminados. Parámetros Todos son de query y ninguno es obligatorio: sin parámetros devuelve la primera página del catálogo completo.
  • search — substring del nombre, sin distinguir mayúsculas (1 a 100 caracteres). El asterisco * funciona como comodín y coincide con cualquier secuencia de caracteres; % y _ se buscan literalmente.
  • cursor — cursor opaco devuelto por la página anterior en next_cursor. Se omite para pedir la primera página. No reutilices un cursor entre endpoints distintos: aunque el formato sea idéntico, cada endpoint lo interpreta sobre su propio conjunto de datos.
  • limit — empleados AI por página. Default 20, máximo 100.
Para recorrer todo el catálogo, repite la llamada pasando el next_cursor de la respuesta anterior hasta que has_more sea false.

​
Respuesta

  • items — arreglo de { name, type }.
  • next_cursor — cursor de la página siguiente; null cuando has_more es false.
  • has_more — indica si hay más resultados después de esta página.

​
Ejemplo

Es una lectura: el GET no asigna ni ejecuta nada, solo devuelve los nombres disponibles para que después los uses en una acción.
Errores
  • 400 — parámetros de query inválidos (INVALID_REQUEST) o cursor corrupto (INVALID_CURSOR).
  • 401 — token ausente, mal formado o no válido (INVALID_API_TOKEN).
  • 403 — el slug del path no coincide con el business del token (TOKEN_BUSINESS_MISMATCH).
  • 429 — rate limit excedido (RATE_LIMIT_EXCEEDED).
  • 500 — error inesperado del servidor (UNKNOWN_ERROR).
Ver el detalle en Errores. El name que devuelve este endpoint es el que va en el campo ai_employee de las acciones que reciben un empleado AI: Asignar y desasignar empleado AI, Ejecutar empleado AI y Asistencia de empleado AI. Recuerda que la asignación persistente solo acepta empleados de tipo operative.