List Agents
curl --request GET \
--url http://localhost:8001/api/v2/list-available-agents \
--header 'x-api-key: <api-key>'import requests
url = "http://localhost:8001/api/v2/list-available-agents"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('http://localhost:8001/api/v2/list-available-agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8001",
CURLOPT_URL => "http://localhost:8001/api/v2/list-available-agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:8001/api/v2/list-available-agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:8001/api/v2/list-available-agents")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8001/api/v2/list-available-agents")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"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"
}
]{
"detail": "Invalid API key"
}Potpie API
List Available Agents
Get a list of all available AI agents using API key authentication
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>'import requests
url = "http://localhost:8001/api/v2/list-available-agents"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('http://localhost:8001/api/v2/list-available-agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8001",
CURLOPT_URL => "http://localhost:8001/api/v2/list-available-agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:8001/api/v2/list-available-agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:8001/api/v2/list-available-agents")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8001/api/v2/list-available-agents")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"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"
}
]{
"detail": "Invalid API key"
}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 thex-api-key header.
x-api-key: YOUR_API_KEY
Response
string
Unique agent identifier (use in conversation creation)
string
Human-readable agent name
string
What the agent specializes in
string
Agent status
string
Visibility of the agent.
null for system agents; private, shared, or public for custom agents.Error Responses
401 Unauthorized
401 Unauthorized
The endpoint requires a valid API key for authentication.Causes:
{
"detail": "API key is required"
}
- Missing
x-api-keyheader - Invalid or expired API key
500 Internal Server Error
500 Internal Server Error
The endpoint returns this error when unexpected exceptions occur.Causes:
{
"detail": "Internal server error"
}
- Database connection failures
- Service unavailability
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}`);
});
import requests
response = requests.get(
'http://localhost:8001/api/v2/list-available-agents',
headers={'x-api-key': 'YOUR_API_KEY'}
)
agents = response.json()
print('Available Agents:')
for agent in agents:
print(f"\n{agent['name']} ({agent['id']})")
print(f" {agent['description']}")
# List all agents
curl -X GET \
'http://localhost:8001/api/v2/list-available-agents' \
-H 'x-api-key: YOUR_API_KEY'
# Pretty print with jq
curl -X GET \
'http://localhost:8001/api/v2/list-available-agents' \
-H 'x-api-key: YOUR_API_KEY' | jq '.'
Troubleshooting
Empty agent list
Empty agent list
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
Unknown agent ID
Unknown agent ID
Problem: Agent ID from list doesn’t work in conversations.Solution:
- Verify you’re using the exact
idvalue from this endpoint - Refresh the agent list to get the latest data
- Some agents may require specific permissions
Authorizations
API key authentication. Get your key from potpie settings page
Was this page helpful?

