Skip to main content
Endpoint · GET /ai-employees
Endpoint somente de consulta: devolve informação e não modifica nada. Não é enviado dentro do array actions — é chamado direto.
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

  • 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.
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. 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, Executar funcionário AI e Assistência de funcionário AI. Lembre-se de que a atribuição persistente só aceita funcionários do tipo operative.