Skip to main content
GET
https://jwhite.tail8bf327.ts.net
/
api
/
v1
/
avatars
List Avatars
curl --request GET \
  --url https://jwhite.tail8bf327.ts.net/api/v1/avatars \
  --header 'x-api-key: <api-key>'
[
  {
    "id": 1,
    "user_id": 123,
    "name": "Professional Avatar",
    "url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1.png",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "is_favorite": 1,
    "is_public": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "user_id": 123,
    "name": "Casual Avatar",
    "url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar2.png",
    "voice_id": null,
    "is_favorite": 0,
    "is_public": 1,
    "created_at": "2024-01-14T09:20:00Z",
    "updated_at": "2024-01-14T09:20:00Z"
  }
]

​
Endpoints

There are three endpoints for listing avatars:
  1. My Avatars (Primary): GET /v1/avatars - Get all avatars for the authenticated user
  2. Public Avatars: GET /v1/avatars/public - Get all publicly available avatars
  3. User Avatars (Deprecated): GET /v1/avatars/user/{userId} - Use the primary endpoint instead

​
Authentication

Requires an API key in the x-api-key header. 
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Request

GET https://jwhite.tail8bf327.ts.net/api/v1/avatars
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Response

[
  {
    "id": 1,
    "user_id": 123,
    "name": "Professional Avatar",
    "url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1.png",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "is_favorite": 1,
    "is_public": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "user_id": 123,
    "name": "Casual Avatar",
    "url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar2.png",
    "voice_id": null,
    "is_favorite": 0,
    "is_public": 1,
    "created_at": "2024-01-14T09:20:00Z",
    "updated_at": "2024-01-14T09:20:00Z"
  }
]

​
Response Fields

FieldTypeDescription
Array of avatar objectsarrayDirect array of avatars (no wrapper object)
idintegerUnique avatar identifier
user_idintegerID of the user who owns the avatar
namestringAvatar name
urlstringURL to avatar image/video
voice_idstringVoice ID associated with this avatar (null if not set)
is_favoriteintegerWhether avatar is marked as favorite (1 = yes, 0 = no)
is_publicintegerWhether avatar is publicly accessible (1 = yes, 0 = no)
created_atstringISO 8601 timestamp of creation
updated_atstringISO 8601 timestamp of last update

​
Notes

  • The primary endpoint GET /v1/avatars automatically returns avatars for the authenticated user
  • Public avatars endpoint returns up to 100 avatars marked as public
  • The /v1/avatars/user/:userId endpoint is deprecated - use the primary endpoint instead
  • Avatars are ordered by created_at in descending order (newest first)
  • Response is a direct array, not wrapped in a success object
  • Each avatar includes a voice_id field - when an agent uses this avatar, it will use this voice
  • This endpoint follows the same pattern as /v1/agents and /v1/sessions for consistency

​
Error Responses

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

​
Common Errors for This Endpoint

  • 401 Unauthorized - Invalid or missing API key
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error