List Agents

GET /api/v1/agents

List all agents in your organization with optional filtering by type, status, and pagination support.

Endpoint

GET https://v2.heppu.ai/api/v1/agents

Authentication

Requires API key authentication via x-api-key or Authorization header.

Query Parameters

Parameter	Type	Required	Default	Description
`type`	string	No	-	Filter by agent type: `voice` or `chat`
`status`	string	No	-	Filter by status: `active`, `inactive`, `training`, `deployed`
`limit`	integer	No	50	Number of results to return (max 100)
`offset`	integer	No	0	Number of results to skip for pagination

Response

Returns an array of agent objects with pagination metadata.

Success Response (200 OK)

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Customer Support Agent",
        "type": "voice",
        "status": "active",
        "model": "gpt-realtime-2025-08-28",
        "instructions": "You are a helpful customer support agent...",
        "config": {
          "voice": "sage",
          "speed": 1.0,
          "interruptionThreshold": 0.5
        },
        "tools": [
          {
            "id": "web_search",
            "name": "Web Search",
            "description": "Search the web for information"
          }
        ],
        "phoneNumbers": ["+1234567890"],
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:00Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Website Chat Assistant",
        "type": "chat",
        "status": "active",
        "model": "gpt-4o",
        "instructions": "You are a friendly website assistant...",
        "config": {
          "theme": "dark",
          "primaryColor": "#3B82F6",
          "position": "bottom-right",
          "greeting": "Hello! How can I help you today?",
          "placeholder": "Type your message...",
          "allowedDomains": ["example.com"]
        },
        "tools": [
          {
            "id": "calculator",
            "name": "Calculator",
            "description": "Perform mathematical calculations"
          }
        ],
        "createdAt": "2025-01-15T11:00:00Z",
        "updatedAt": "2025-01-15T11:00:00Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 2,
      "hasMore": false
    }
  }
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": 401
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "message": "Internal server error",
    "code": 500
  }
}

Examples

cURL

# List all agents
curl -X GET "https://v2.heppu.ai/api/v1/agents" \
  -H "x-api-key: YOUR_API_KEY"

# List only voice agents
curl -X GET "https://v2.heppu.ai/api/v1/agents?type=voice" \
  -H "x-api-key: YOUR_API_KEY"

# List active chat agents with pagination
curl -X GET "https://v2.heppu.ai/api/v1/agents?type=chat&status=active&limit=10&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript

// Using fetch
const response = await fetch('https://v2.heppu.ai/api/v1/agents?type=voice', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result.data.agents);

// Using axios
const axios = require('axios');

const response = await axios.get('https://v2.heppu.ai/api/v1/agents', {
  params: {
    type: 'chat',
    status: 'active',
    limit: 20
  },
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

console.log(response.data.data.agents);

Python

import requests

# List all agents
response = requests.get(
    'https://v2.heppu.ai/api/v1/agents',
    headers={'x-api-key': 'YOUR_API_KEY'}
)

result = response.json()
agents = result['data']['agents']

# List with filters
response = requests.get(
    'https://v2.heppu.ai/api/v1/agents',
    params={
        'type': 'voice',
        'status': 'active',
        'limit': 10,
        'offset': 0
    },
    headers={'x-api-key': 'YOUR_API_KEY'}
)

result = response.json()
for agent in result['data']['agents']:
    print(f"{agent['name']} - {agent['type']}")

Node.js (with TypeScript)

interface Agent {
  id: string;
  name: string;
  type: 'voice' | 'chat';
  status: string;
  model: string;
  instructions: string;
  config: Record<string, any>;
  tools: Array<{
    id: string;
    name: string;
    description: string;
  }>;
  phoneNumbers?: string[];
  createdAt: string;
  updatedAt: string;
}

interface ListAgentsResponse {
  success: boolean;
  data: {
    agents: Agent[];
    pagination: {
      limit: number;
      offset: number;
      total: number;
      hasMore: boolean;
    };
  };
}

async function listAgents(
  type?: 'voice' | 'chat',
  status?: string,
  limit = 50,
  offset = 0
): Promise<Agent[]> {
  const params = new URLSearchParams();
  if (type) params.append('type', type);
  if (status) params.append('status', status);
  params.append('limit', limit.toString());
  params.append('offset', offset.toString());

  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents?${params}`,
    {
      headers: {
        'x-api-key': process.env.HEPPU_API_KEY!,
      },
    }
  );

  const result: ListAgentsResponse = await response.json();
  return result.data.agents;
}

// Usage
const voiceAgents = await listAgents('voice', 'active');

Pagination

The API uses offset-based pagination. To paginate through results:

Make initial request with limit and offset=0
Check pagination.hasMore in the response
If true, make next request with offset increased by limit
Repeat until hasMore is false

async function getAllAgents() {
  const allAgents = [];
  let offset = 0;
  const limit = 50;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://v2.heppu.ai/api/v1/agents?limit=${limit}&offset=${offset}`,
      {
        headers: { 'x-api-key': 'YOUR_API_KEY' }
      }
    );

    const result = await response.json();
    allAgents.push(...result.data.agents);

    hasMore = result.data.pagination.hasMore;
    offset += limit;
  }

  return allAgents;
}

Response Fields

Voice Agent Fields

phoneNumbers: Array of phone numbers assigned to the agent
config: Contains voice-specific settings like voice, speed, interruptionThreshold

Chat Agent Fields

config: Contains widget settings like theme, primaryColor, position, greeting, placeholder, allowedDomains

Notes

Agents are automatically scoped to your organization
The total count in pagination represents the number of agents in the current page, not the total count of all agents
Use hasMore: true to determine if there are more results to fetch
Maximum limit value is 100
Phone numbers are only included for voice agents
Deleted agents have status: "inactive" and are still returned in the list

Create Agent - Create a new agent
Get Agent - Get detailed agent information
Update Agent - Update agent configuration
Delete Agent - Delete an agent

List Agents

On this page