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

# AI employees

> Query the business catalog of runnable AI employees

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

<Note>
  **Read-only** endpoint: it returns information and changes nothing. It is not sent inside the `actions` array — you call it directly.
</Note>

Returns the business's **runnable** and active AI employees, in alphabetical order
and paginated by cursor. This is where the exact `name` required by the actions
that take an AI employee comes from: the API identifies them by name, not by id,
so this catalog is how you find out which names exist before assembling an action.

Each item carries its `type`:

* `operative` — can be assigned to the conversation and also run.
* `json` — can only be run one-off. Assigning it with `assign_ai_employee` fails
  with `AI_EMPLOYEE_NOT_FOUND`.

The catalog omits inactive and deleted AI employees.

**Parameters**

All of them are query params and **none is required**: with no parameters it
returns the first page of the full catalog.

* `search` — case-insensitive substring of the name (1 to 100 characters). The
  asterisk `*` works as a wildcard and matches any sequence of characters; `%` and
  `_` are matched literally.
* `cursor` — opaque cursor returned by the previous page in `next_cursor`. Omit it
  to request the first page. Do not reuse a cursor across different endpoints:
  even though the format is identical, each endpoint interprets it over its own
  data set.
* `limit` — AI employees per page. Default `20`, maximum `100`.

To walk the whole catalog, repeat the call passing the `next_cursor` from the
previous response until `has_more` is `false`.

### Response

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

* `items` — array of `{ name, type }`.
* `next_cursor` — cursor for the next page; `null` when `has_more` is `false`.
* `has_more` — whether there are more results after this page.

### Example

This is a read: the `GET` neither assigns nor runs anything, it only returns the
available names so you can use them later in an action.

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

```bash theme={null}
# filter by name and request the next page
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/ai-employees?search=ventas&limit=50&cursor=eyJuIjoiQ2xhc2lmaWNhZG9yIn0" \
  -H "Authorization: Bearer sk_1to1_your_api_key"
```

**Errors**

* `400` — invalid query params (`INVALID_REQUEST`) or corrupt cursor (`INVALID_CURSOR`).
* `401` — missing, malformed or invalid token (`INVALID_API_TOKEN`).
* `403` — the path slug does not match the token's business (`TOKEN_BUSINESS_MISMATCH`).
* `429` — rate limit exceeded (`RATE_LIMIT_EXCEEDED`).
* `500` — unexpected server error (`UNKNOWN_ERROR`).

See the detail in [Errors](/en/errors).

The `name` returned by this endpoint is the one that goes in the `ai_employee`
field of the actions that take an AI employee:
[Assign and unassign AI employee](/en/action-groups/ai-employee),
[Run AI employee](/en/action-groups/run-ai) and
[AI employee assistance](/en/action-groups/ai-assistance). Remember that
persistent assignment only accepts employees of type `operative`.