> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Empleados AI

> Consulta el catálogo de empleados AI ejecutables del business

<Info>
  **Endpoint** · `GET /ai-employees`
</Info>

<Note>
  Endpoint de **solo consulta**: devuelve información y no modifica nada. No se manda dentro del array `actions` — se llama directo.
</Note>

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

```json theme={null}
{
  "items": [
    { "name": "Asistente de Ventas", "type": "operative" },
    { "name": "Clasificador de Intención", "type": "json" }
  ],
  "next_cursor": "eyJuIjoiQ2xhc2lmaWNhZG9yIn0",
  "has_more": true
}
```

* `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.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/ai-employees" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

```bash theme={null}
# filtrar por nombre y pedir la página siguiente
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/ai-employees?search=ventas&limit=50&cursor=eyJuIjoiQ2xhc2lmaWNhZG9yIn0" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

**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](/es/errors).

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](/es/action-groups/ai-employee),
[Ejecutar empleado AI](/es/action-groups/run-ai) y
[Asistencia de empleado AI](/es/action-groups/ai-assistance). Recuerda que la
asignación persistente solo acepta empleados de tipo `operative`.