Create, retrieve, update, and delete Ready Player Me cross-platform avatars. Includes template-based creation, asset equipping, draft management, color palette discovery, and binary glTF (.glb) plus 2D PNG renders used in Unity, Unreal, web, iOS, and Android. Supports A/T-pose, mesh LODs, texture atlases, ARKit / Oculus morph targets, Draco and Meshopt compression.
openapi: 3.0.3
info:
title: Ready Player Me Assets Avatars API
description: 'List, filter, and retrieve Ready Player Me assets — hair, outfits, headwear,
glasses, facewear, footwear, beards, costumes, and custom assets — that can be
equipped on avatars. Assets are scoped to an application (`X-APP-ID`) and can be
further filtered to those visible or usable by a specific user.
'
version: '1.0'
contact:
name: Ready Player Me Developers
url: https://docs.readyplayer.me/
servers:
- url: https://api.readyplayer.me
description: Production
security:
- AppId: []
tags:
- name: Avatars
description: Avatar creation, asset equipping, render, and lifecycle operations.
paths:
/v2/avatars:
post:
summary: Create A Draft Avatar
operationId: createAvatar
tags:
- Avatars
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AvatarCreateRequest'
responses:
'201':
description: Draft avatar created.
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
/v2/avatars/templates:
get:
summary: List Avatar Templates
operationId: listAvatarTemplates
tags:
- Avatars
responses:
'200':
description: A list of available avatar templates.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AvatarTemplate'
/v2/avatars/templates/{templateId}:
post:
summary: Create Avatar From Template
operationId: createAvatarFromTemplate
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/TemplateId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AvatarCreateRequest'
responses:
'201':
description: Avatar created from template.
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
/v2/avatars/{avatarId}:
get:
summary: Get Avatar Metadata
operationId: getAvatarMetadata
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
responses:
'200':
description: Avatar metadata JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
patch:
summary: Update Avatar Equipped Assets
operationId: updateAvatar
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
- name: responseType
in: query
schema:
type: string
enum:
- glb
- json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AvatarUpdateRequest'
responses:
'200':
description: Avatar updated.
put:
summary: Save Draft Avatar
operationId: saveAvatar
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
responses:
'200':
description: Draft avatar saved as a permanent avatar.
delete:
summary: Delete Avatar
operationId: deleteAvatar
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
responses:
'204':
description: Avatar deleted.
/v2/avatars/{avatarId}/draft:
delete:
summary: Delete Avatar Draft
operationId: deleteAvatarDraft
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
responses:
'204':
description: Avatar draft discarded.
/v2/avatars/{avatarId}/precompile:
post:
summary: Precompile Avatar Render
operationId: precompileAvatar
tags:
- Avatars
description: Warm the asset cache for a specific avatar / parameter combination.
parameters:
- $ref: '#/components/parameters/AvatarId'
responses:
'200':
description: Precompile accepted.
/v2/avatars/{avatarId}/colors:
get:
summary: Get Avatar Color Palette
operationId: getAvatarColors
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
- name: type
in: query
schema:
type: string
description: Comma-separated color categories (skin,beard,hair,eyebrow).
example: skin,beard,hair,eyebrow
responses:
'200':
description: Avatar color palette.
content:
application/json:
schema:
$ref: '#/components/schemas/ColorPalette'
/v1/avatars:
get:
summary: List Avatars For A User
operationId: listUserAvatars
tags:
- Avatars
parameters:
- name: userId
in: query
required: true
schema:
type: string
- name: select
in: query
schema:
type: string
example: id,partner
responses:
'200':
description: A list of avatars owned by the user.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Avatar'
/v1/avatars/{avatarId}.glb:
get:
summary: Get Avatar GLB Model
operationId: getAvatarGlb
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
- name: pose
in: query
schema:
type: string
enum:
- A
- T
description: A-pose or T-pose.
- name: meshLod
in: query
schema:
type: integer
enum:
- 0
- 1
- 2
description: Mesh level of detail.
- name: textureAtlas
in: query
schema:
type: string
enum:
- none
- '256'
- '512'
- '1024'
- '2048'
- name: textureSizeLimit
in: query
schema:
type: integer
enum:
- 256
- 512
- 1024
- 2048
- name: textureChannels
in: query
schema:
type: string
description: Comma-separated texture channels.
example: baseColor,normal,metallicRoughness,emissive,occlusion
- name: morphTargets
in: query
schema:
type: string
description: ARKit / Oculus / custom morph targets, or "none".
example: ARKit
- name: useHands
in: query
schema:
type: boolean
- name: useDracoMeshCompression
in: query
schema:
type: boolean
- name: useMeshOptCompression
in: query
schema:
type: boolean
responses:
'200':
description: Binary glTF avatar model.
content:
model/gltf-binary:
schema:
type: string
format: binary
/v1/avatars/{avatarId}.png:
get:
summary: Get 2D Avatar Render
operationId: getAvatarPng
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
- name: scene
in: query
schema:
type: string
enum:
- fullbody-portrait-v1
- fullbody-portrait-v1-transparent
- halfbody-portrait-v1
- halfbody-portrait-v1-transparent
- portrait-v1
- portrait-v1-transparent
- name: w
in: query
schema:
type: integer
- name: h
in: query
schema:
type: integer
- name: cacheControl
in: query
schema:
type: boolean
responses:
'200':
description: PNG render of the avatar.
content:
image/png:
schema:
type: string
format: binary
/v2/avatars/{avatarId}.glb:
get:
summary: Get V2 Avatar GLB Model
operationId: getAvatarGlbV2
tags:
- Avatars
parameters:
- $ref: '#/components/parameters/AvatarId'
- name: preview
in: query
schema:
type: boolean
responses:
'200':
description: Binary glTF avatar model.
content:
model/gltf-binary:
schema:
type: string
format: binary
components:
schemas:
ColorPalette:
type: object
properties:
data:
type: object
additionalProperties:
type: array
items:
type: string
description: Hex color value.
AvatarUpdateRequest:
type: object
properties:
data:
type: object
properties:
assets:
type: object
additionalProperties:
type: string
Avatar:
type: object
properties:
id:
type: string
partner:
type: string
userId:
type: string
bodyType:
type: string
enum:
- halfbody
- fullbody
gender:
type: string
enum:
- masculine
- feminine
- neutral
assets:
type: object
additionalProperties:
type: string
AvatarCreateRequest:
type: object
properties:
data:
type: object
properties:
partner:
type: string
bodyType:
type: string
gender:
type: string
assets:
type: object
AvatarTemplate:
type: object
properties:
id:
type: string
imageUrl:
type: string
gender:
type: string
parameters:
TemplateId:
name: templateId
in: path
required: true
schema:
type: string
AvatarId:
name: avatarId
in: path
required: true
schema:
type: string
securitySchemes:
AppId:
type: apiKey
in: header
name: X-APP-ID