Skip to main content
GET
/
v1
/
agents
curl "https://api.ringyo.ai/v1/agents?limit=10&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Sales Assistant",
      "voice_id": "sarah-professional",
      "language": "en-US",
      "model": "gpt-4o",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-18T14:22:00Z"
    },
    {
      "id": "agent_def456",
      "name": "Support Agent",
      "voice_id": "michael-friendly",
      "language": "en-US",
      "model": "gpt-4o-mini",
      "status": "active",
      "created_at": "2024-01-10T08:15:00Z",
      "updated_at": "2024-01-10T08:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 2
}

​
Request

Retrieve a paginated list of all AI voice agents in your account.

​
Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_API_KEY

​
Query Parameters

​
limit
integer
default:"20"
Number of agents to return (1-100)
​
cursor
string
Pagination cursor from a previous response
​
status
string
Filter by status: active or inactive
​
search
string
Search agents by name
​
order
string
default:"desc"
Sort order: asc or desc (by created_at)

​
Response

​
data
array
Array of agent objects
​
has_more
boolean
Whether there are more results available
​
next_cursor
string
Cursor for fetching the next page
​
total
integer
Total number of agents matching the filter
curl "https://api.ringyo.ai/v1/agents?limit=10&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Sales Assistant",
      "voice_id": "sarah-professional",
      "language": "en-US",
      "model": "gpt-4o",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-18T14:22:00Z"
    },
    {
      "id": "agent_def456",
      "name": "Support Agent",
      "voice_id": "michael-friendly",
      "language": "en-US",
      "model": "gpt-4o-mini",
      "status": "active",
      "created_at": "2024-01-10T08:15:00Z",
      "updated_at": "2024-01-10T08:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 2
}

​
Error Codes

CodeDescription
invalid_cursorThe pagination cursor is invalid or expired
invalid_statusStatus must be ‘active’ or ‘inactive’