List avatars

GET

/v1/avatars

const url = 'https://example.com/v1/avatars?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/v1/avatars?limit=20' \
  --header 'Authorization: Bearer <token>'

List avatars available to the calling org. Includes platform-built-in demos (e.g. av_demo) and any customer-uploaded avatars.

Authorizations

ApiKey

Parameters

Query Parameters

limit

Limit

Page size. Default 20, max 100.

integer

default: 20 >= 1 <= 100

Page size. Default 20, max 100.

starting_after

Any of:

string
null

string

Pagination cursor — an av_… id from a previous page.

Responses

200

Successful Response

application/json

AvatarList

Cursor-paginated list of avatars.

object

data

required

Array<object>

Avatar

Public Avatar resource returned by GET /v1/avatars and GET /v1/avatars/{id}.

object

created_at

required

string format: date-time

required

av_… prefixed ULID.

string

is_demo

required

True for platform built-in avatars (e.g. av_demo).

boolean

name

required

string

object

string

default: avatar

Allowed value: avatar

runtime_type

required

Runtime that serves this avatar (e.g. mock, gaussian).

string

status

required

AvatarStatus

Lifecycle of a custom avatar.

ready — usable for sessions. processing — being fitted / converted. failed — fitting failed; will not be usable without re-upload.

string

Allowed values: ready processing failed

has_more

required

boolean

next_cursor

Any of:

string
null

string

object

string

default: list

Allowed value: list

Example

{
  "data": [],
  "has_more": false,
  "object": "list"
}

401

Missing or invalid API key.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}

422

Request body or parameters failed validation.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}