Get Agent

GET /api/v1/agents/{agentId}

Get detailed information about a specific agent, including its configuration, assigned tools, and phone numbers (for voice agents).

Endpoint

GET https://v2.heppu.ai/api/v1/agents/{agentId}

Authentication

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

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent UUID to retrieve

Response

Returns detailed information about the agent.

Success Response (200 OK)

Voice Agent Response

{
  "success": true,
  "data": {
    "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. Be polite, professional, and help customers resolve their issues efficiently.",
    "config": {
      "voice": "sage",
      "speed": 1.0,
      "interruptionThreshold": 0.5,
      "timeout": 30
    },
    "tools": [
      {
        "id": "web_search",
        "name": "Web Search",
        "description": "Search the web for information",
        "category": "information",
        "config": {}
      },
      {
        "id": "calendar",
        "name": "Calendar",
        "description": "Manage calendar events and appointments",
        "category": "productivity",
        "config": {}
      }
    ],
    "phoneNumbers": ["+1234567890", "+1987654321"],
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
}

Chat Agent Response

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Website Chat Assistant",
    "type": "chat",
    "status": "active",
    "model": "gpt-4o",
    "instructions": "You are a friendly website assistant. Help users navigate the site, answer questions about products and services, and provide excellent customer support.",
    "config": {
      "theme": "dark",
      "primaryColor": "#3B82F6",
      "position": "bottom-right",
      "greeting": "Hello! How can I help you today?",
      "placeholder": "Type your message...",
      "allowedDomains": ["example.com", "www.example.com"]
    },
    "tools": [
      {
        "id": "calculator",
        "name": "Calculator",
        "description": "Perform mathematical calculations",
        "category": "utility",
        "config": {}
      }
    ],
    "createdAt": "2025-01-15T11:00:00Z",
    "updatedAt": "2025-01-15T11:00:00Z"
  }
}

Error Responses

401 Unauthorized

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

404 Not Found

{
  "success": false,
  "error": {
    "message": "Agent not found",
    "code": 404
  }
}

Examples

cURL

# Get agent details
curl -X GET "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

# Get agent with Authorization header
curl -X GET "https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

// Using fetch
const getAgent = async (agentId) => {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

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

// Usage
const agent = await getAgent('550e8400-e29b-41d4-a716-446655440000');
console.log(`Agent: ${agent.name}`);
console.log(`Type: ${agent.type}`);
console.log(`Status: ${agent.status}`);
console.log(`Tools: ${agent.tools.map(t => t.name).join(', ')}`);

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

const response = await axios.get(
  'https://v2.heppu.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

const agent = response.data.data;

Python

import requests

def get_agent(agent_id):
    response = requests.get(
        f'https://v2.heppu.ai/api/v1/agents/{agent_id}',
        headers={'x-api-key': 'YOUR_API_KEY'}
    )

    if response.status_code != 200:
        error = response.json()
        raise Exception(error['error']['message'])

    return response.json()['data']

# Usage
agent_id = '550e8400-e29b-41d4-a716-446655440000'
agent = get_agent(agent_id)

print(f"Agent: {agent['name']}")
print(f"Type: {agent['type']}")
print(f"Status: {agent['status']}")
print(f"Model: {agent['model']}")
print(f"Tools: {', '.join([t['name'] for t in agent['tools']])}")

if agent['type'] == 'voice':
    print(f"Phone Numbers: {', '.join(agent['phoneNumbers'])}")

Node.js (with TypeScript)

interface Tool {
  id: string;
  name: string;
  description: string;
  category: string;
  config: Record<string, any>;
}

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

interface GetAgentResponse {
  success: boolean;
  data: Agent;
}

async function getAgent(agentId: string): Promise<Agent> {
  const response = await fetch(
    `https://v2.heppu.ai/api/v1/agents/${agentId}`,
    {
      headers: {
        'x-api-key': process.env.HEPPU_API_KEY!,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

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

// Usage
const agent = await getAgent('550e8400-e29b-41d4-a716-446655440000');

console.log(`Agent: ${agent.name}`);
console.log(`Type: ${agent.type}`);
console.log(`Model: ${agent.model}`);

// Type-safe access to voice agent phone numbers
if (agent.type === 'voice' && agent.phoneNumbers) {
  console.log(`Phone Numbers: ${agent.phoneNumbers.join(', ')}`);
}

// Access tools
agent.tools.forEach(tool => {
  console.log(`- ${tool.name}: ${tool.description}`);
});

Response Fields

Common Fields (All Agent Types)

Field	Type	Description
`id`	string	Unique agent identifier (UUID)
`name`	string	Agent name
`type`	string	Agent type (`voice` or `chat`)
`status`	string	Agent status (`active`, `inactive`, `training`, `deployed`)
`model`	string	OpenAI model identifier
`instructions`	string	Agent behavior instructions (system prompt)
`config`	object	Type-specific configuration
`tools`	array	Array of enabled tool objects
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Voice Agent Specific Fields

Field	Type	Description
`phoneNumbers`	array	Array of assigned phone numbers

Tool Object

Field	Type	Description
`id`	string	Tool identifier
`name`	string	Tool name
`description`	string	Tool description
`category`	string	Tool category (`information`, `productivity`, `utility`, etc.)
`config`	object	Tool-specific configuration

Use Cases

Check Agent Status

async function isAgentActive(agentId) {
  const agent = await getAgent(agentId);
  return agent.status === 'active';
}

Get Agent Phone Numbers

async function getAgentPhoneNumbers(agentId) {
  const agent = await getAgent(agentId);

  if (agent.type !== 'voice') {
    throw new Error('Agent is not a voice agent');
  }

  return agent.phoneNumbers || [];
}

List Agent Tools

async function getAgentTools(agentId) {
  const agent = await getAgent(agentId);
  return agent.tools.map(tool => ({
    id: tool.id,
    name: tool.name,
    category: tool.category
  }));
}

async function getWidgetConfig(agentId) {
  const agent = await getAgent(agentId);

  if (agent.type !== 'chat') {
    throw new Error('Agent is not a chat agent');
  }

  return agent.config;
}

Notes

Agent data is scoped to your organization
Only agents belonging to your organization can be retrieved
The phoneNumbers field is only present for voice agents
Tools include detailed information including category and configuration
All timestamps are in ISO 8601 format (UTC)
The config object structure varies based on agent type
Inactive/deleted agents can still be retrieved (status will be inactive)

List Agents - Get all agents
Create Agent - Create a new agent
Update Agent - Update agent configuration
Delete Agent - Delete an agent