Skip to main content
GET
/
api
/
v2
/
platform
/
agents
Get All Agents
curl --request GET \
  --url http://localhost:3001/api/v2/platform/agents/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'
{
  "count": 94,
  "status_code": 200,
  "message": "Agents fetched successfully",
  "data": [
    {
      "handle": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "name": "General Agentic",
      "type": "Voice",
      "state": "published",
      "purpose": "Handle outbound sales calls"
    }
  ]
}

{
  "count": 94,
  "status_code": 200,
  "message": "Agents fetched successfully",
  "data": [
    {
      "handle": "space-agent-8qmk42nslp91wrh3dz7btxc4",
      "name": "General Agentic",
      "type": "Voice",
      "state": "published",
      "purpose": "Handle outbound sales calls"
    }
  ]
}

​
Get All Agents

Retrieve detailed information for all registered AI agents in your organization, helping you view and manage agent records within the system.
Prerequisites: Make sure you have your API Token and Org-Handle ready. See Authentication for details.

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization domain handle
You can get the Org-Handle by hitting the Get All Organizations API. The domain_handle field in the response is your Org-Handle.

​
Response Fields

FieldTypeDescription
countintegerTotal number of agents
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of agent objects

​
Agent Object Fields

FieldTypeDescription
handlestringUnique agent handle/identifier
namestringAgent display name
typestringAgent type: Voice, Chat, etc.
statestringAgent state: published, draft, archived
purposestringAgent purpose/use case description

​
Common Error Codes

Status CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters provided
401Unauthorized - Invalid or missing API token
403Forbidden - Access denied to the resource
404Not Found - Organization not found
500Internal Server Error - Server-side error

​
Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Org-Handle': 'your-org-handle'
};

// Get all agents
const getAllAgents = async () => {
  const response = await axios.get(
    'https://unpod.dev/api/v2/platform/agents/',
    { headers }
  );
  console.log(`Total agents: ${response.data.count}`);
  response.data.data.forEach(agent => {
    console.log(`${agent.name} (${agent.handle}) - ${agent.state}`);
  });
  return response.data.data;
};

// Example usage
getAllAgents();

​
Best Practices

  1. Agent Handle: Note the handle field — it is used as the agent_handle path parameter in other agent endpoints
  2. State Filtering: Filter by state in your application to show only published agents
  3. Org-Handle: Always include the correct organization handle in requests
  4. Error Handling: Always handle potential errors and edge cases
  5. Security: Keep API tokens secure and rotate them regularly

Authorizations

​
Authorization
string
header
required

Format: Token

Headers

​
Org-Handle
string
required

Organization domain handle

Example:

"unpod"

Response

List of all agents