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

# Funcionários de IA

> Consulte o catálogo de funcionários de IA executáveis do business

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

<Note>
  Endpoint **somente de consulta**: devolve informação e não modifica nada. Não é enviado dentro do array `actions` — é chamado direto.
</Note>

Devolve os funcionários de IA **executáveis** e ativos do business, em ordem
alfabética e paginados por cursor. É daqui que sai o `name` exato exigido pelas
ações que recebem um funcionário de IA: a API os identifica por nome, não por id,
então este catálogo é a forma de saber quais nomes existem antes de montar uma
ação.

Cada item traz o seu `type`:

* `operative` — pode ser atribuído à conversa e também executado.
* `json` — só pode ser executado de forma pontual. Atribuí-lo com
  `assign_ai_employee` falha com `AI_EMPLOYEE_NOT_FOUND`.

O catálogo omite os funcionários de IA inativos e os excluídos.

**Parâmetros**

Todos são de query e **nenhum é obrigatório**: sem parâmetros devolve a primeira
página do catálogo completo.

* `search` — substring do nome, sem diferenciar maiúsculas (1 a 100 caracteres). O
  asterisco `*` funciona como curinga e corresponde a qualquer sequência de
  caracteres; `%` e `_` são buscados literalmente.
* `cursor` — cursor opaco devolvido pela página anterior em `next_cursor`. Omita
  para pedir a primeira página. Não reutilize um cursor entre endpoints
  diferentes: mesmo que o formato seja idêntico, cada endpoint o interpreta sobre
  o seu próprio conjunto de dados.
* `limit` — funcionários de IA por página. Padrão `20`, máximo `100`.

Para percorrer todo o catálogo, repita a chamada passando o `next_cursor` da
resposta anterior até que `has_more` seja `false`.

### Resposta

```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 de `{ name, type }`.
* `next_cursor` — cursor da página seguinte; `null` quando `has_more` é `false`.
* `has_more` — indica se há mais resultados depois desta página.

### Exemplo

É uma leitura: o `GET` não atribui nem executa nada, apenas devolve os nomes
disponíveis para que você os use depois em uma ação.

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

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

**Erros**

* `400` — parâmetros de query inválidos (`INVALID_REQUEST`) ou cursor corrompido (`INVALID_CURSOR`).
* `401` — token ausente, malformado ou inválido (`INVALID_API_TOKEN`).
* `403` — o slug do path não coincide com o business do token (`TOKEN_BUSINESS_MISMATCH`).
* `429` — rate limit excedido (`RATE_LIMIT_EXCEEDED`).
* `500` — erro inesperado do servidor (`UNKNOWN_ERROR`).

Veja o detalhe em [Erros](/pt/errors).

O `name` que este endpoint devolve é o que vai no campo `ai_employee` das ações
que recebem um funcionário de IA:
[Atribuir e desatribuir funcionário AI](/pt/action-groups/ai-employee),
[Executar funcionário AI](/pt/action-groups/run-ai) e
[Assistência de funcionário AI](/pt/action-groups/ai-assistance). Lembre-se de que
a atribuição persistente só aceita funcionários do tipo `operative`.