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

# Listar Agentes

> Recuperar uma lista de agentes de voz com opções de filtragem e paginação

# Listar Agentes

Recuperar uma lista de agentes de voz para o ambiente autenticado com várias opções de filtragem e suporte à paginação.

## Endpoint

```
GET /api/v1/agents
```

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

## Parâmetros de consulta

<ParamField query="status" type="string" required={false}>
  Filtrar por status do agente. Opções: `draft`, `published`, `unpublished`
</ParamField>

<ParamField query="language" type="string" required={false}>
  Filtrar por idioma do agente (ex: `en-US`, `pt-BR`)
</ParamField>

<ParamField query="search" type="string" required={false}>
  Pesquisar no nome ou descrição do agente
</ParamField>

<ParamField query="per_page" type="integer" required={false}>
  Número de itens por página (padrão: 20, máximo: 100)
</ParamField>

<ParamField query="page" type="integer" required={false}>
  Número da página (padrão: 1)
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # Requisição 1: Obter todos os agentes
  curl -X GET "https://app.talkover.ai/api/v1/agents" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 1: Obter todos os agentes
  const response = await fetch('https://app.talkover.ai/api/v1/agents', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Requisição 2: Obter agentes publicados em português
  curl -X GET "https://app.talkover.ai/api/v1/agents?status=published&language=pt-BR&per_page=50" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 2: Obter agentes publicados em português
  const response = await fetch('https://app.talkover.ai/api/v1/agents?status=published&language=pt-BR&per_page=50', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Requisição 3: Pesquisar por nome específico
  curl -X GET "https://app.talkover.ai/api/v1/agents?search=Atendimento" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Requisição 3: Pesquisar por nome específico
  const response = await fetch('https://app.talkover.ai/api/v1/agents?search=Atendimento', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "agent-uuid-1",
        "name": "Agente de Atendimento",
        "description": "Agente especializado em atendimento ao cliente",
        "status": "published",
        "language": "pt-BR",
        "voice_template_id": "voice-template-uuid-1",
        "voice_template_name": "Bianca",
        "knowledge_base": "Base de conhecimento para atendimento",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "agent-uuid-2",
        "name": "Agente de Vendas",
        "description": "Agente especializado em vendas e prospecção",
        "status": "draft",
        "language": "pt-BR",
        "voice_template_id": "voice-template-uuid-2",
        "voice_template_name": "Isabela",
        "knowledge_base": "Base de conhecimento para vendas",
        "created_at": "2024-01-01T01:00:00Z",
        "updated_at": "2024-01-01T01:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 20,
      "total": 100,
      "from": 1,
      "to": 20
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="data" type="array" required>
  Array de objetos de agente.

  <Expandable title="Objeto de Agente">
    <ResponseField name="id" type="string" required>
      Identificador único do agente.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Nome do agente.
    </ResponseField>

    <ResponseField name="description" type="string">
      Descrição do agente.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status atual do agente. Opções: `draft`, `published`, `unpublished`.
    </ResponseField>

    <ResponseField name="language" type="string" required>
      Idioma do agente (ex: `pt-BR`, `en-US`).
    </ResponseField>

    <ResponseField name="voice_template_id" type="string" required>
      ID do modelo de voz associado ao agente.
    </ResponseField>

    <ResponseField name="voice_template_name" type="string" required>
      Nome do modelo de voz associado ao agente.
    </ResponseField>

    <ResponseField name="knowledge_base" type="string" required>
      Base de conhecimento do agente.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      Timestamp ISO 8601 quando o agente foi criado.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      Timestamp ISO 8601 quando o agente foi atualizado pela última vez.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Metadados de paginação.

  <Expandable title="Objeto de Paginação">
    <ResponseField name="current_page" type="integer" required>
      Número da página atual.
    </ResponseField>

    <ResponseField name="last_page" type="integer" required>
      Número da última página.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Número de itens por página.
    </ResponseField>

    <ResponseField name="total" type="integer" required>
      Número total de itens.
    </ResponseField>

    <ResponseField name="from" type="integer" required>
      Número do item inicial da página atual.
    </ResponseField>

    <ResponseField name="to" type="integer" required>
      Número do item final da página atual.
    </ResponseField>
  </Expandable>
</ResponseField>

## Respostas de erro

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "status": [
        "The selected status is invalid."
      ],
      "language": [
        "The selected language is invalid."
      ]
    }
  }
  ```
</ResponseExample>

### 500 Erro do Servidor

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## Códigos de erro

| Código             | Descrição                                   | Status HTTP |
| ------------------ | ------------------------------------------- | ----------- |
| `INVALID_TOKEN`    | Token de autenticação inválido ou ausente   | 401         |
| `VALIDATION_ERROR` | Validação dos parâmetros de consulta falhou | 422         |
| `SERVER_ERROR`     | Erro interno do servidor ocorreu            | 500         |

## Notas Importantes

<Info>
  **Suporte à paginação.** Todos os endpoints de lista suportam paginação com parâmetros `page` e `per_page`.
</Info>

<Info>
  **Filtros disponíveis.** Use parâmetros de consulta para filtrar agentes por status, idioma e pesquisa.
</Info>

<Info>
  **Funcionalidade de pesquisa.** O parâmetro de pesquisa busca no nome e descrição dos agentes.
</Info>

## Melhores Práticas

1. **Use paginação** - Sempre use paginação para grandes conjuntos de dados
2. **Filtre por status** - Use filtros de status para encontrar agentes publicados ou em rascunho
3. **Pesquise eficientemente** - Use o parâmetro de pesquisa para encontrar agentes específicos rapidamente
4. **Monitore status** - Filtre por status para acompanhar o progresso dos agentes
5. **Trate erros** - Implemente tratamento adequado de erros para falhas de autenticação e validação

## Endpoints relacionados

* **Criar Agente**: `POST /api/v1/agents`
* **Obter Agente**: `GET /api/v1/agents/{agent_id}`
* **Atualizar Conhecimento do Agente**: `PUT /api/v1/agents/{agent_id}/knowledge`
* **Excluir Agente**: `DELETE /api/v1/agents/{agent_id}`