List avatars

Return the avatars (agent pictures) you can pick for the agent. The avatar sets the agent's image, gender and nationality.

GEThttps://api.spyne.ai/conversation/avatars

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous, one database read

Every active generic avatar is returned. Pass teamId to add the custom avatars owned by that rooftop. Nothing is stored.

Auth: Bearer token of a signed-in user, checked with the identity service. Rate limit: not documented. Processing: synchronous, one database read.

Before you call it

teamId is optional. Pass it to include the rooftop's custom avatars.
Unknown query parameters are rejected with 400.

Query parameters

Optionalcan be left out

Parameter	Type	Required	Description
`teamId`	string	Optional	Rooftop. Adds that rooftop's custom avatars to the generic ones.
`gender`	string	Optional	`male` or `female`.
`nationality`	string	Optional	Exact nationality label, for example `american`.
`age`	string	Optional	`young`, `middle_aged` or `old`.

Sample request

curl -G "https://api.spyne.ai/conversation/avatars" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "teamId=<teamId>" \
  --data-urlencode "gender=female"

import requests

res = requests.get(
    "https://api.spyne.ai/conversation/avatars",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"teamId": "<teamId>", "gender": "female"},
)
print(res.status_code, res.json())

const params = new URLSearchParams({ teamId: '<teamId>', gender: 'female' });
const res = await fetch(`https://api.spyne.ai/conversation/avatars?${params}`, {
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});
console.log(res.status, await res.json());

Sample response

[
  {
    "avatarId": "<avatarId>",
    "name": "Example Avatar",
    "imageUrl": "https://example.com/avatar.png",
    "gender": "female",
    "nationality": "american",
    "age": "middle_aged",
    "isGeneric": true
  }
]

{
  "statusCode": 400,
  "message": "Failed to retrieve avatars",
  "errorCode": "BAD_REQUEST",
  "timestamp": "2026-10-12T10:00:00.000Z",
  "requestId": "req_1760263200000_abc123xyz",
  "context": {},
  "path": "/conversation/avatars",
  "method": "GET"
}

A 401 has the same shape as on Browse the voice library.

Response parameters (200)

The body is an array. Each item has these fields.

Parameter	Type	Description
`[].avatarId`	string	Send this as `avatarId` when you save the agent.
`[].teamId`	string	Set only on a rooftop's custom avatar.
`[].name`	string	Display name.
`[].imageUrl`	string	Image URL.
`[].gender`	string	`male` or `female`.
`[].nationality`	string	Nationality label.
`[].age`	string	`young`, `middle_aged` or `old`.
`[].isGeneric`	boolean	`true` when the avatar is not tied to a rooftop.

Errors

Status	Reason	When it happens
`400`	Validation failed	A filter value is not allowed, or an unknown query parameter was sent.
`400`	Failed to retrieve avatars	The database read failed.
`401`	Authentication failed	Missing or rejected token.

What happens next

Send the chosen avatarId in Create an agent, where it is required, or in Update an agent.