Skip to main content
GET
/
api
/
agents
curl -X GET "https://api.zudu.ai/api/agents?limit=10&page=0&sort_by=created_at&sort_order=descending" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \

{
  "message": "Agents retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "agents": [
      {
        "agent_id": "agent_1234567890abcdef",
        "agent_name": "Customer Support Agent",
        "language": "en",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "agent_id": "agent_abcdef1234567890",
        "agent_name": "Sales Agent",
        "language": "en",
        "created_at": "2024-01-14T09:20:00Z",
        "updated_at": "2024-01-14T09:20:00Z"
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 10,
      "total": 25,
      "total_pages": 3
    },
    "returned_count": 2,
    "sort_order": "descending",
    "sort_by": "created_at"
  }
Retrieve a paginated list of all agents belonging to your organization with optional sorting and pagination. 
curl -X GET "https://api.zudu.ai/api/agents?limit=10&page=0&sort_by=created_at&sort_order=descending" \
  -H "X-API-KEY: sk_Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234Yz" \
  -H "X-API-SECRET: s3cr3t_Xyz789Abc123Def456Ghi789Jkl012Mno345Pqr678Stu901Vwx234" \

{
  "message": "Agents retrieved successfully",
  "status": "success",
  "error": null,
  "data": {
    "organization_id": "org_1234567890",
    "agents": [
      {
        "agent_id": "agent_1234567890abcdef",
        "agent_name": "Customer Support Agent",
        "language": "en",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "agent_id": "agent_abcdef1234567890",
        "agent_name": "Sales Agent",
        "language": "en",
        "created_at": "2024-01-14T09:20:00Z",
        "updated_at": "2024-01-14T09:20:00Z"
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 10,
      "total": 25,
      "total_pages": 3
    },
    "returned_count": 2,
    "sort_order": "descending",
    "sort_by": "created_at"
  }

​
Query Parameters

​
limit
integer
Number of agents to return per page (default: 10)
  • Minimum: 1
  • Maximum: 100
Example: 10
​
page
integer
Page number (0-indexed) (default: 0)Example: 0 for the first page, 1 for the second page
​
sort_by
string
Field to sort by (default: created_at)Valid values: created_at, updated_at, agent_nameExample: created_at
​
sort_order
string
Sort order (default: descending)Valid values: ascending, descendingExample: descending

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Response Fields

​
organization_id
string
The organization ID
​
agents
array
Array of agent objectsEach agent object contains:
  • agent_id: Unique identifier
  • agent_name: Name of the agent
  • language: Language code
  • created_at: Creation timestamp
  • updated_at: Last update timestamp
  • Additional agent configuration fields
​
pagination
object
Pagination metadata
  • page: Current page number (0-indexed)
  • limit: Number of items per page
  • total: Total number of agents
  • total_pages: Total number of pages
​
returned_count
integer
Number of agents returned in this response
​
sort_order
string
Sort order applied (ascending or descending)
​
sort_by
string
Field used for sorting

​
Error Responses

​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Internal Server Error - Failed to retrieve agents
{
  "message": "Failed to retrieve agents",
  "status": "error",
  "error": "Database connection failed"
}

​
Notes

  • Results are automatically scoped to your organization based on the API key (organization ID is automatically extracted)
  • If limit is not provided, all agents will be returned (not recommended for large organizations)
  • The endpoint uses optimized database queries for better performance
  • Sorting is case-insensitive for string fields
  • Use pagination to handle large result sets efficiently