Skip to main content
GET
https://jwhite.tail8bf327.ts.net
/
api
/
v1
/
agents
List Agents
curl --request GET \
  --url https://jwhite.tail8bf327.ts.net/api/v1/agents \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "agents": [
    {
      "agent_id": 123,
      "name": "Sales Support Agent",
      "avatar_id": 1,
      "language": "en",
      "custom_greeting": "Welcome! How can I assist you today?",
      "context": "You are a helpful sales assistant.",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "last_used_at": "2024-01-15T12:00:00Z",
      "total_sessions": 5,
      "avg_duration": 120.5,
      "avatar_name": "Professional Avatar",
      "avatar_url": "https://example.com/avatar.jpg",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    }
  ]
}

​
Authentication

Requires JWT authentication (cookie-based) or API key in the x-api-key header. 
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Request

GET https://jwhite.tail8bf327.ts.net/api/v1/agents
Authorization: Bearer <jwt_token>

​
Response

{
  "success": true,
  "agents": [
    {
      "agent_id": 123,
      "name": "Sales Support Agent",
      "avatar_id": 1,
      "language": "en",
      "custom_greeting": "Welcome! How can I assist you today?",
      "context": "You are a helpful sales assistant.",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "last_used_at": "2024-01-15T12:00:00Z",
      "total_sessions": 5,
      "avg_duration": 120.5,
      "avatar_name": "Professional Avatar",
      "avatar_url": "https://example.com/avatar.jpg",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    }
  ]
}

​
Response Fields

FieldTypeDescription
successbooleanWhether the request was successful
agentsarrayArray of agent objects
agents[].agent_idintegerUnique agent identifier
agents[].namestringAgent name
agents[].avatar_idintegerAvatar ID
agents[].languagestringLanguage code
agents[].custom_greetingstringCustom greeting message
agents[].contextstringAI context/instructions
agents[].statusstringAgent status
agents[].created_atstringISO 8601 creation timestamp
agents[].updated_atstringISO 8601 last update timestamp
agents[].last_used_atstringISO 8601 last usage timestamp
agents[].total_sessionsintegerTotal number of sessions
agents[].avg_durationnumberAverage session duration in seconds
agents[].avatar_namestringAvatar display name
agents[].avatar_urlstringAvatar image URL
agents[].voice_idstringVoice ID from the avatar (null if avatar has no voice)

​
Notes

  • Agents are ordered by updated_at in descending order (most recently updated first)
  • The response includes aggregated session statistics (total_sessions, avg_duration)
  • Avatar information is joined and included (avatar_name, avatar_url, voice_id)
  • The voice_id comes from the avatar, not the agent directly
  • Each agent can have multiple sessions (calls)

​
Error Responses

For information about error responses and status codes, see Error Responses.

​
Common Errors for This Endpoint

  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Insufficient permissions
  • 500 Internal Server Error - Server error