> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# API Reference - Agents

Manage your agents using the Paygent API. List agents with pagination, or use the `ensure` endpoint to create or retrieve an agent by its external ID.

## List Agents

Returns a paginated list of agents. Use `page` and `limit` query parameters to control pagination.

```bash
curl --location 'https://cp-api.withpaygent.com/api/v1/agents?page=1&limit=20' \
--header 'paygent-api-key: YOUR_API_KEY'
```

## Ensure Agent

Create a new agent or retrieve an existing one. This is useful for auto-discovering agents from external systems like LiveKit or basic LLM tracking.

```bash
curl --location 'https://cp-api.withpaygent.com/api/v1/agents/ensure' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "agent_name": "My Discovery Agent",
    "agent_external_id": "agent_unique_123",
    "agent_description": "Auto-discovered agent",
    "agent_type": "voice"
  }'
```