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

Name	Type	Description
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.

201: Created A typical successful response

{
    "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",
    }
}

400: Bad Request A validation error

{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request",
    "data": {
        "body": [
            {
                "instancePath": "/data",
                "schemaPath": "#/properties/data/required",
                "keyword": "required",
                "params": {
                    "missingProperty": "name"
                },
                "message": "must have required property 'name'"
            }
        ]
    }
}

403: Forbidden A permissions error

{
    "type": "ForbiddenError",
    "status": 403,
    "message": "Cannot execute \"create\" on \"Asset\""
}

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

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

Path Parameters

Name	Type	Description
id*	string	The id of the asset you want to update.

Request Body

Name	Type	Description
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.

201: Created A typical successful response

{
    "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",
    }
}

400: Bad Request A validation error

{
    "type": "BadRequestError",
    "status": 400,
    "message": "Bad Request",
    "data": {
        "body": [
            {
                "instancePath": "/data/name",
                "schemaPath": "#/properties/data/properties/name/minLength",
                "keyword": "minLength",
                "params": {
                    "limit": 1
                },
                "message": "must NOT have fewer than 1 characters"
            }
        ]
    }
}

403: Forbidden A permissions error

{
    "type": "ForbiddenError",
    "status": 403,
    "message": "Cannot execute \"update\" on \"Asset\""
}

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

Name	Type	Description
*	String	The id of the asset you want to unlock

Request Body

Name	Type	Description
data.userId*	String	The id of the user you want to unlock the asset for

204: No Content If the asset was successfully unlocked for the user, it would return status 204. No response body is sent

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

Name	Type	Description
*	String	The id of the asset you want to lock

Request Body

Name	Type	Description
data.userId*	String	The id of the user you want to lock the asset for

204: No Content If the asset was successfully locked for the user, it would return status 204. No response body is sent

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

Name	Type	Description
*	String	The id of the avatar you want to equip the asset to

Request Body

Name	Type	Description
data.assetId*	String	The id of the asset you want to equip

204: No Content If the asset were successfully equipped to the avatar, it would return status 204. No response body is sent.

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

Name	Type	Description
*	String	The id of the avatar you want to remove the asset from

Request Body

Name	Type	Description
data.assetId*	String	The id of the asset you want to unequip

204: No Content If the asset were successfully unequipped from the avatar, it would return status 204. No response body is sent.