Skip to main content
GET
/
api
/
v2
/
list-available-agents
List Agents
curl --request GET \
  --url http://localhost:8001/api/v2/list-available-agents \
  --header 'x-api-key: <api-key>'
[
  {
    "id": "codebase_qna_agent",
    "name": "Codebase Q&A Agent",
    "description": "An agent specialized in answering questions about the codebase using the knowledge graph and code analysis tools",
    "status": "active",
    "visibility": "public"
  },
  {
    "id": "debugging_agent",
    "name": "Debugging Agent",
    "description": "An agent specialized in debugging using knowledge graphs",
    "status": "active",
    "visibility": "public"
  }
]

​
Use Cases

  • Discover available agents before creating conversations
  • Build agent selection interfaces in your application
  • Understand agent capabilities and specializations
  • Dynamically populate agent options for users
  • Determine the right agent for specific tasks

​
Authentication

This endpoint requires API key authentication via the x-api-key header. 
x-api-key: YOUR_API_KEY

​
Response

​
id
string
Unique agent identifier (use in conversation creation)
​
name
string
Human-readable agent name
​
description
string
What the agent specializes in
​
status
string
Agent status
​
visibility
string
Visibility of the agent. null for system agents; private, shared, or public for custom agents.

​
Error Responses

The endpoint requires a valid API key for authentication.
{
  "detail": "API key is required"
}
Causes:
  • Missing x-api-key header
  • Invalid or expired API key
Solution: Include a valid API key in the request header.
The endpoint returns this error when unexpected exceptions occur.
{
  "detail": "Internal server error"
}
Causes:
  • Database connection failures
  • Service unavailability
Solution: Retry the request after a brief delay. Contact support if the issue persists.

​
Complete Workflow

const response = await fetch(
  'http://localhost:8001/api/v2/list-available-agents',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

const agents = await response.json();

console.log('Available Agents:');
agents.forEach(agent => {
  console.log(`\n${agent.name} (${agent.id})`);
  console.log(`  ${agent.description}`);
});

​
Troubleshooting

Problem: API returns an empty array [].Solution:
  • This is unusual - system agents should always be available
  • Verify you’re using the correct API endpoint
  • Check that your account is active and in good standing
  • Contact support if the list remains empty
Problem: Agent ID from list doesn’t work in conversations.Solution:
  • Verify you’re using the exact id value from this endpoint
  • Refresh the agent list to get the latest data
  • Some agents may require specific permissions

Authorizations

​
x-api-key
string
header
required

API key authentication. Get your key from potpie settings page

Response

Agents retrieved successfully

​
id
string

Agent identifier

​
name
string

Agent display name

​
description
string

Agent capabilities and use cases

​
status
string

Agent availability status

​
visibility
string

Agent visibility (public/private)