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

# List Agents

> Retrieve a list of voice agents with optional filtering and pagination

# List Agents

Retrieve a list of voice agents with optional filtering by status, direction, and search terms. Supports pagination for large datasets.

## Endpoint

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

## Path parameters

None

## Query parameters

<ParamField query="status" type="string" required={false}>
  Filter by agent status. Options: `draft`, `published`
</ParamField>

<ParamField query="direction" type="string" required={false}>
  Filter by call direction. Options: `inbound`, `outbound`
</ParamField>

<ParamField query="search" type="string" required={false}>
  Search by agent name or label
</ParamField>

<ParamField query="per_page" type="integer" required={false}>
  Number of items per page (default: 20)
</ParamField>

<ParamField query="page" type="integer" required={false}>
  Page number for pagination (default: 1)
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: List all agents
  curl -X GET "https://app.talkover.ai/api/v1/agents" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 1: List all agents
  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}
  # Request 2: List published inbound agents
  curl -X GET "https://app.talkover.ai/api/v1/agents?status=published&direction=inbound" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 2: List published inbound agents
  const response = await fetch('https://app.talkover.ai/api/v1/agents?status=published&direction=inbound', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

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

<RequestExample>
  ```bash theme={null}
  # Request 3: Search agents with pagination
  curl -X GET "https://app.talkover.ai/api/v1/agents?search=support&per_page=5&page=1" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 3: Search agents with pagination
  const response = await fetch('https://app.talkover.ai/api/v1/agents?search=support&per_page=5&page=1', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

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

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "SupportBot",
        "label": "Customer Support Agent",
        "description": "Handles customer inquiries and support requests",
        "language": "en-US",
        "voice": {
          "id": "voice-uuid",
          "name": "Bianca",
          "label": "Bianca Voice",
          "stability": 0.6,
          "similarity_boost": 0.98,
          "ambient_background": "office",
          "template": {
            "id": "voice-template-uuid",
            "name": "Bianca"
          }
        },
        "initial_message": "Hello, how can I help you today?",
        "interrupt_sensitivity": "medium",
        "conversation_speed": 1.0,
        "initial_message_delay": 0,
        "ask_if_human_present_on_idle": false,
        "direction": "inbound",
        "who_speaks_first": "agent",
        "current_status": "published",
        "is_sandbox": false,
        "is_ready_to_publish": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "trainings": [
          {
            "id": "training-uuid",
            "subject": "Product Knowledge",
            "instructions": "Learn about our product features and pricing",
            "current_status": "active",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:00Z"
          }
        ],
        "actions": [
          {
            "id": "action-uuid",
            "name": "Schedule Meeting",
            "label": "Schedule Meeting",
            "description": "Schedule a meeting with the customer",
            "type": "webhook",
            "input_schema": [
              {
                "name": "date",
                "type": "string",
                "required": true,
                "description": "Meeting date"
              }
            ],
            "config": null,
            "action_trigger": null,
            "url": "https://api.example.com/schedule",
            "authorization_url": null,
            "current_status": "active",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-15T10:30:00Z"
          }
        ],
        "phone_numbers": [
          {
            "id": "phone-uuid",
            "number": "+1234567890",
            "country_code": "US",
            "formatted_number": "(123) 456-7890",
            "international_number": "+1 234 567 890",
            "current_status": "active"
          }
        ]
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 10,
      "total": 25,
      "last_page": 3
    }
  }
  ```
</ResponseExample>

## Error responses

### Validation Error (422)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "status": [
        "The selected status is invalid."
      ],
      "direction": [
        "The selected direction is invalid."
      ],
      "per_page": [
        "The per page must be between 1 and 100."
      ]
    }
  }
  ```
</ResponseExample>

### Unauthorized Error (401)

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

### Too Many Requests (429)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>