Avatar v2

Reference for the Avatar v2 endpoints on Roblox.

Base URL: https://avatar.roblox.com

Endpoints

Method	Path	Name
`PATCH`	`/v2/avatar`	`patchAvatar`
`GET`	`/v2/avatar/avatar`	`getAvatarAvatar`
`POST`	`/v2/avatar/set-body-colors`	`postAvatarSetBodyColors`
`POST`	`/v2/avatar/set-wearing-assets`	`postAvatarSetWearingAssets`
`GET`	`/v2/avatar/users/:userId/avatar`	`getAvatarUsersUseridAvatar`
`GET`	`/v2/avatar/users/:userId/outfits`	`getAvatarUsersUseridOutfits`
`PATCH`	`/v2/outfits/:userOutfitId`	`patchOutfitsUseroutfitid`
`POST`	`/v2/outfits/create`	`postOutfitsCreate`

`patchAvatar`

PATCH /v2/avatar

Sets the avatar to the incoming avatar using field masks.

Usage

import { fetchApi } from 'rozod';
import { patchAvatar } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(patchAvatar, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`updateMask`	`0	1
`data`	`object`	See below

data fields:

Field	Type	Description
`scales`	`object`	See below
`playerAvatarType`	`1	3`
`bodyColors`	`object`	See below
`assets`	`object[]`	See below

scales fields:

Field	Type	Description
`height`	`number`
`width`	`number`
`head`	`number`
`depth`	`number`
`proportion`	`number`
`bodyType`	`number`

bodyColors fields:

Field	Type	Description
`headColor3`	`string`
`torsoColor3`	`string`
`rightArmColor3`	`string`
`leftArmColor3`	`string`
`rightLegColor3`	`string`
`leftLegColor3`	`string`

assets[] item fields:

Field	Type	Description
`id`	`number`
`meta`	`object`	See below

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`object`
`Y`	`object`
`Z`	`object`

rotation fields:

Field	Type	Description
`X`	`object`
`Y`	`object`
`Z`	`object`

scale fields:

Field	Type	Description
`X`	`object`
`Y`	`object`
`Z`	`object`

Response

Field	Type	Description
`invalidAssets`	`object[]`	See below
`success`	`boolean`

invalidAssets[] item fields:

Field	Type	Description
`id`	`number`
`name`	`string`
`assetType`	`object`	See below
`currentVersionId`	`number`
`meta`	`object`	See below
`availabilityStatus`	`string`
`expirationTime`	`string`
`supportsHeadShapes`	`boolean`

assetType fields:

Field	Type	Description
`id`	`number`
`name`	`string`

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

Errors

Status	Description
400	3: Invalid assetId 5: Meta does not apply to specified asset type 7: Required meta is not provided for the specific asset type
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed
500	2: Failed to wear asset.

`getAvatarAvatar`

GET /v2/avatar/avatar

Returns details about the authenticated user’s avatar.

Usage

import { fetchApi } from 'rozod';
import { getAvatarAvatar } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(getAvatarAvatar, {
  checkAssetAvailability: /* boolean? */
});

Parameters

Name	Type	Required	Description
`checkAssetAvailability`	`boolean?`	No	Whether to return assets with availability status.

Response

Field	Type	Description
`scales`	`object`	See below
`playerAvatarType`	`1	3`
`bodyColor3s`	`object`	See below
`assets`	`object[]`	See below
`defaultShirtApplied`	`boolean`
`defaultPantsApplied`	`boolean`
`emotes`	`object[]`	See below

scales fields:

Field	Type	Description
`height`	`number`
`width`	`number`
`head`	`number`
`depth`	`number`
`proportion`	`number`
`bodyType`	`number`

bodyColor3s fields:

Field	Type	Description
`headColor3`	`string`
`torsoColor3`	`string`
`rightArmColor3`	`string`
`leftArmColor3`	`string`
`rightLegColor3`	`string`
`leftLegColor3`	`string`

assets[] item fields:

Field	Type	Description
`id`	`number`
`name`	`string`
`assetType`	`object`	See below
`currentVersionId`	`number`
`meta`	`object`	See below
`availabilityStatus`	`string`
`expirationTime`	`string`
`supportsHeadShapes`	`boolean`

assetType fields:

Field	Type	Description
`id`	`number`
`name`	`string`

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

emotes[] item fields:

Field	Type	Description
`assetId`	`number`
`assetName`	`string`
`position`	`number`

Errors

Status	Description
401	0: Authorization has been denied for this request.

`postAvatarSetBodyColors`

POST /v2/avatar/set-body-colors

Sets the authenticated user’s body colors.

Usage

import { fetchApi } from 'rozod';
import { postAvatarSetBodyColors } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(postAvatarSetBodyColors, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`headColor3`	`string`
`torsoColor3`	`string`
`rightArmColor3`	`string`
`leftArmColor3`	`string`
`rightLegColor3`	`string`
`leftLegColor3`	`string`

Response

Field	Type	Description
`success`	`boolean`

Errors

Status	Description
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed

`postAvatarSetWearingAssets`

POST /v2/avatar/set-wearing-assets

Sets the avatar’s current assets to the list.

Usage

import { fetchApi } from 'rozod';
import { postAvatarSetWearingAssets } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(postAvatarSetWearingAssets, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`assets`	`object[]`	See below

assets[] item fields:

Field	Type	Description
`id`	`number`
`meta`	`object`	See below

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

Response

Field	Type	Description
`invalidAssets`	`object[]`	See below
`invalidAssetIds`	`number[]`
`success`	`boolean`

invalidAssets[] item fields:

Field	Type	Description
`id`	`number`
`name`	`string`
`assetType`	`object`	See below
`currentVersionId`	`number`
`meta`	`object`	See below
`availabilityStatus`	`string`
`expirationTime`	`string`
`supportsHeadShapes`	`boolean`

assetType fields:

Field	Type	Description
`id`	`number`
`name`	`string`

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

Errors

Status	Description
400	3: Invalid assetId 5: Meta does not apply to specified asset type 7: Required meta is not provided for the specific asset type
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed
500	2: Failed to wear asset.

`getAvatarUsersUseridAvatar`

GET /v2/avatar/users/:userId/avatar

Returns details about a specified user’s avatar.

Usage

import { fetchApi } from 'rozod';
import { getAvatarUsersUseridAvatar } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(getAvatarUsersUseridAvatar, {
  userId: /* integer */,
  checkAssetAvailability: /* boolean? */
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes
`checkAssetAvailability`	`boolean?`	No	Whether to return assets with availability status.

Response

Field	Type	Description
`scales`	`object`	See below
`playerAvatarType`	`1	3`
`bodyColor3s`	`object`	See below
`assets`	`object[]`	See below
`defaultShirtApplied`	`boolean`
`defaultPantsApplied`	`boolean`
`emotes`	`object[]`	See below

scales fields:

Field	Type	Description
`height`	`number`
`width`	`number`
`head`	`number`
`depth`	`number`
`proportion`	`number`
`bodyType`	`number`

bodyColor3s fields:

Field	Type	Description
`headColor3`	`string`
`torsoColor3`	`string`
`rightArmColor3`	`string`
`leftArmColor3`	`string`
`rightLegColor3`	`string`
`leftLegColor3`	`string`

assets[] item fields:

Field	Type	Description
`id`	`number`
`name`	`string`
`assetType`	`object`	See below
`currentVersionId`	`number`
`meta`	`object`	See below
`availabilityStatus`	`string`
`expirationTime`	`string`
`supportsHeadShapes`	`boolean`

assetType fields:

Field	Type	Description
`id`	`number`
`name`	`string`

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

emotes[] item fields:

Field	Type	Description
`assetId`	`number`
`assetName`	`string`
`position`	`number`

Errors

Status	Description
400	1: The specified user does not exist. 2: An account for the given userId does not exist!

`getAvatarUsersUseridOutfits`

GET /v2/avatar/users/:userId/outfits

Gets a list of outfits for the specified user.

Usage

import { fetchApi } from 'rozod';
import { getAvatarUsersUseridOutfits } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(getAvatarUsersUseridOutfits, {
  userId: /* integer */,
  paginationToken: /* string? */,
  outfitType: /* string? */,
  page: /* integer? = 1 */,
  itemsPerPage: /* integer? = 25 */,
  isEditable: /* boolean? */
});

Parameters

Name	Type	Required	Description
`userId`	`integer`	Yes	The user id.
`paginationToken`	`string?`	No	The token received from the response to get the next page. For the first request, this value should be empty. Note : If no value is sent the 1st page will be returned.
`outfitType`	`string?`	No	The outfit type being searched for, null will return all outfitTypes.
`page`	`integer? = 1`	No	The page number of the current page of requests, default is 1.
`itemsPerPage`	`integer? = 25`	No	The max number of outfits that can be returned.
`isEditable`	`boolean?`	No	Whether the outfits are editable. A null value will lead to no filtering.

Response

Field	Type	Description
`data`	`object[]`	See below
`paginationToken`	`string`

data[] item fields:

Field	Type	Description
`id`	`number`
`name`	`string`
`isEditable`	`boolean`
`outfitType`	`string`

Errors

Status	Description
400	1: The specified user does not exist. 2: An account for the given userId does not exist!

`patchOutfitsUseroutfitid`

PATCH /v2/outfits/:userOutfitId

Updates the contents of an outfit.

Usage

import { fetchApi } from 'rozod';
import { patchOutfitsUseroutfitid } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(patchOutfitsUseroutfitid, {
  userOutfitId: /* integer */,
  body: { /* ... */ }
});

Parameters

Name	Type	Required	Description
`userOutfitId`	`integer`	Yes	The user outfit id.

Request Body

Field	Type	Description
`name`	`string`
`bodyColors`	`object`	See below
`assets`	`object[]`	See below
`scale`	`object`	See below
`playerAvatarType`	`string`
`outfitType`	`0	1

bodyColors fields:

Field	Type	Description
`headColorId`	`number`
`torsoColorId`	`number`
`rightArmColorId`	`number`
`leftArmColorId`	`number`
`rightLegColorId`	`number`
`leftLegColorId`	`number`

assets[] item fields:

Field	Type	Description
`id`	`number`
`meta`	`object`	See below

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`height`	`number`
`width`	`number`
`head`	`number`
`depth`	`number`
`proportion`	`number`
`bodyType`	`number`

Response

Field	Type	Description
`id`	`number`
`name`	`string`
`isEditable`	`boolean`
`outfitType`	`string`

Errors

Status	Description
400	3: Body colors must be valid BrickColor IDs 4: Invalid outfit name 5: Asset is not wearable by you 8: Invalid Player Avatar Type. Valid types are R6 and R15 11: Meta does not apply to specified asset type 12: Meta is required for this specific asset type 13: Invalid Outfit Type 14: Invalid scale
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: You don't have permission to update this outfit.
404	1: The specified userOutfit does not exist!
500	6: An error occurred while trying to update the outfit

`postOutfitsCreate`

POST /v2/outfits/create

Creates a new outfit.

Usage

import { fetchApi } from 'rozod';
import { postOutfitsCreate } from 'rozod/endpoints/avatarv2';

const data = await fetchApi(postOutfitsCreate, {
  body: { /* ... */ }
});

Request Body

Field	Type	Description
`name`	`string`
`bodyColors`	`object`	See below
`assets`	`object[]`	See below
`scale`	`object`	See below
`playerAvatarType`	`string`
`outfitType`	`0	1

bodyColors fields:

Field	Type	Description
`headColorId`	`number`
`torsoColorId`	`number`
`rightArmColorId`	`number`
`leftArmColorId`	`number`
`rightLegColorId`	`number`
`leftLegColorId`	`number`

assets[] item fields:

Field	Type	Description
`id`	`number`
`meta`	`object`	See below

meta fields:

Field	Type	Description
`order`	`number`
`puffiness`	`number`
`position`	`object`	See below
`rotation`	`object`	See below
`scale`	`object`	See below
`headShape`	`0	1
`staticFacialAnimation`	`boolean`
`version`	`number`

position fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

rotation fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`X`	`number`
`Y`	`number`
`Z`	`number`

scale fields:

Field	Type	Description
`height`	`number`
`width`	`number`
`head`	`number`
`depth`	`number`
`proportion`	`number`
`bodyType`	`number`

Response

Type: unknown

Errors

Status	Description
400	3: Body colors must be valid BrickColor IDs 4: Invalid outfit name 5: Asset is not wearable by you and was not added to the outfit 7: Invalid Player Avatar Type. Valid types are R6 and R15 8: Invalid assetIds 9: Meta does not apply to specified asset type 10: Required meta is not provided for the specific asset type 12: Outfit type invalid or not permitted 13: Invalid Scale
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 1: You already have the maximum number of outfits
500	6: An error occurred while creating the outfit