Unlocking assets through API (Beta)

Unlock/lock specific assets for certain users through API calls

This documentation covers a set of API endpoints to manage assets for users, including unlocking and locking them and equipping and unequipping them on avatars.

Authorizing requests:

For all subsequent requests to the Asset endpoints, you need an API Key. Please go to Studio -> API Keys to create one.

You can authorize by adding x-api-key to the header of the request.

--header 'x-api-key: {your-api-key}'

Refer to API docs for more info about common error codes and else.

The API key needs to have "WRITE" permissions for Users, Assets and Avatars.

1. Create a locked asset

Before you can start unlocking an asset for users you need to have an asset that is locked - not usable without unlocking. You can think of a locked = true asset as premium, something that needs to be bought or earned and locked = false as free.

Use this endpoint to create a new locked asset by setting locked property as true

POST https://api.readyplayer.me/v1/assets

Request Body

NameTypeDescription

data.name*

string

Minimum length of 1 character

data.type*

enum(string)

Possible values:

outfit

data.gender*

enum(string)

Possible values:

male

,

female

data.modelUrl*

url

Must be a valid url pointing to a GLB file.

data.iconUrl*

url

Must be a valid url pointing to a PNG or JPG file.

data.organizationId*

string

The id of the organization you wish to create the asset under.

\

\

This is directly linked to your permissions, and you will only be able to create assets for organizations which you have permission to.

data.applicationIds

array

List of application ids, this asset should be added to. If empty, this asset is not added to any application.

data.locked

boolean

If set as true, the created asset is not usable without unlocking it for the specific user first.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "male",
        "iconUrl": "https://www.example.org/logo.png",
        "modelUrl": "https://www.example.org/model.glb",
        "status": "draft",
        "organizationId": "63a58eb6df136d3df8ce0d74",
        "name": "My new asset",
        "applicationIds": [],
        "createdAt": "2023-03-13T13:54:22.559Z",
        "updatedAt": "2023-03-13T13:54:22.559Z",
        "publishedAt": "2023-03-13T13:54:22.559Z",
    }
}

Use this endpoint to turn an existing asset into a locked asset

PATCH https://api.readyplayer.me/v1/assets/:id

Path Parameters

NameTypeDescription

id*

string

The id of the asset you want to update.

Request Body

NameTypeDescription

data.name

string

Minimum length of 1 character

data.type

enum(string)

Possible values:

outfit

data.gender

enum(string)

Possible values:

male

,

female

data.modelUrl

url

Must be a valid url pointing to a GLB file.

data.iconUrl

url

Must be a valid url pointing to a PNG or JPG file.

data.locked

String

If set as true, the asset is not usable without unlocking it for the specific user first.

{
    "data": {
        "id": "640f2b0ed1dbab604a9955d0",
        "type": "outfit",
        "gender": "female",
        "iconUrl": "https://example.org/icon.png",
        "modelUrl": "https://example.org/model.glb",
        "status": "draft",
        "organizationId": "53a58ec6df126a3df8ce0d72",
        "name": "Asset test updated",
        "applicationIds": [],
        "createdAt": "2023-03-14T09:32:31.423Z",
        "updatedAt": "2023-03-14T09:32:48.804Z",
        "publishedAt": "2023-03-14T09:32:48.804Z",
    }
}

See Manage custom outfits using the API for more information about asset management.

2. Unlock an Asset for the User

Locked assets should be unlocked first to be usable by the user. You should unlock the asset for the user after they have successfully purchased it or claimed through other means.

Use this endpoint for unlocking an asset for a user

PUT https://api.readyplayer.me/v1/assets/:id/unlock

Path Parameters

NameTypeDescription

*

String

The id of the asset you want to unlock

Request Body

NameTypeDescription

data.userId*

String

The id of the user you want to unlock the asset for

If the asset is already unlocked for this user, the endpoint will respond with an error.

While the user might initiate the flow, such as by making a purchase, ensure that the call is made from your backend, as it involves your API key.

3. Lock an Asset for a User

You can lock a previously unlocked asset for a given user.

Use this endpoint for locking an unlocked asset for a user

PUT https://api.readyplayer.me/v1/assets/:id/lock

Path Parameters

NameTypeDescription

*

String

The id of the asset you want to lock

Request Body

NameTypeDescription

data.userId*

String

The id of the user you want to lock the asset for

If the asset hasn’t been unlocked for this user, this endpoint will respond with an error.

Successfully calling this endpoint will also automatically unequip this asset from all of the user’s avatars.

4. Equip an Asset on an Avatar

If you unlocked an asset for a user, you can equip the asset to any of your user’s avatars.

Use this endpoint to equip an unlocked asset to a user's avatar

PUT https://api.readyplayer.me/v1/avatars/:id/equip

Path Parameters

NameTypeDescription

*

String

The id of the avatar you want to equip the asset to

Request Body

NameTypeDescription

data.assetId*

String

The id of the asset you want to equip

5. Unequip an Asset from an Avatar

Similarly, as with equip-asset, you can also unequip an asset from an avatar.

In the request’s body, provide the avatar’s ID and the asset’s ID.

Use this endpoint to unequip an asset from a user's avatar

PUT https://api.readyplayer.me/v1/avatars/:id/unequip

Path Parameters

NameTypeDescription

*

String

The id of the avatar you want to remove the asset from

Request Body

NameTypeDescription

data.assetId*

String

The id of the asset you want to unequip

Last updated