Usage Guide for Assets

The Assets API of Open Cloud allows you to upload and update assets with a single HTTP request rather than manually importing them to Studio. This API supports:

• Uploading new assets.
• Updating existing assets with version control.
• Updating asset metadata, including descriptions, display names, icons, and previews.
• Managing asset versions, such as rolling back to a specified previous version.
• Checking existing information of an asset, including metadata, versions, and any in-process updating operations.

Supported Asset Types and Limits

For endpoints that don't create a new asset or update the content of existing assets, there are no restrictions and limits. However, the asset content uploading functionality powered by the Create Asset and Update Asset endpoints only supports limited types of assets with restrictions. For each call, you can only create or update one asset with the file size up to 20 MB with the following limits:

Security Permissions

The API supports both first-party use with API key authorization and third-party use in OAuth 2 applications. Each way requires different security permission settings.

API Keys

To use the API in your own scripts or tools, you need to Create an API key for authorization and security. To manage assets that you own individually, create the API key under your account. To manage group-owned assets, create the API key under the target group. For more information on group-owned API keys, see Group-Owned API Key Permissions.

Once you create an API key, you can't switch its ownership between individuals or groups, so if you create an API key under your own account, you can't use it for managing group assets.

Regardless of whether you are creating the API key for yourself or your group, make sure to add the following permissions:

1. Add Assets API to Access Permissions.
2. Add Read and Write operation permissions to your selected experience, depending on the required scopes of the endpoints you plan to call.

Once you have the API key, copy it to the x-api-key request header. All endpoints require the x-api-key request header.

Example API Request Header
--header 'x-api-key: ${ApiKey}' \

OAuth 2.0 Apps

To use the API for a third-party OAuth 2.0 application, add the asset:read and asset:write permission scopes when registering your app. Choose these scopes based on the requirements of the endpoints you plan to use.

Creating a New Asset

To upload a new asset by an HTTP request:

1. Copy the API key to the x-api-key request header of the Create Asset endpoint.

2. In your request:

   1. Specify the target asset type.
   2. Add your asset name and description.
   3. Add the creator information.

      • If you want to create the asset on your own behalf, add your user ID. You can find your user ID on the URL of your Roblox profile. For example, for https://www.roblox.com/users/1234567/profile, your user ID is 1234567.
      • If you want to create the asset as a group asset, add the group ID of your group. You can find the group ID on the URL of your group's page. For example, for https://www.roblox.com/groups/7654321/example-group#!/, the group ID is 7654321.
   4. Add the file path and content type of your asset.

   Example Request for Create Asset
   curl --location 'https://apis.roblox.com/assets/v1/assets' \
   --header 'x-api-key: ${ApiKey}' \
   --form 'request="{
     \"assetType\": \"Model\",
     \"displayName\": \"Name\",
     \"description\": \"This is a description\",
     \"creationContext\": {
       \"creator\": {
         \"userId\": \"${userId}\" # Use groupId for creating a group asset
       }
     }
   }"' \
   --form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Updating an Existing Asset

To update an existing asset by an HTTP request:

1. Copy the API key to the x-api-key request header of the Update Asset endpoint.
2. Add the asset type and asset ID in your request. To copy your asset ID:

   1. Navigate to the Creation page of the Creator Dashboard.
   2. Select the Development Items category.
   3. Select the category of your asset and find the target asset.
   4. Hover over the thumbnail of the target asset and click the ⋯ button to display a list of options, then select Copy Asset ID from the list.

Example Request for Updating Asset Content
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \
--header 'x-api-key: {apiKey}' \
--form 'request={
    \"assetType\": \"{assetType}\",
    \"assetId\": \"{assetId}\",
    \"creationContext\": { 
        \"creator\": {
            \"userId\": {userId}
        },
        \"expectedPrice\":{expectedPrice}
    },
}' \
--form 'fileContent=@"{file-path}"'

Retrieving Asset Operation Status

If your request for creating a new asset or updating an existing asset succeeds, it returns an Operation ID in the format of { "path": "operations/${operationId}" }. You can use it to check the status and result of your upload with the following steps:

1. Copy the API key to the x-api-key request header of the Get Operation method and send the request, like the following code sample:

   Example Request for Get Operation
   curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \
   --header 'x-api-key: {$ApiKey}'

2. If your request succeeds, it returns an Operation object, either including a response representing the uploaded asset information or a status explaining why the asset upload fails as the following code sample shows:

   Example Response for Get Operation
   {
     "path": "operations/{operationId}",
     "done": true,
     "response": {
       "@type": "type.googleapis.com/roblox.open_cloud.assets.v1.Asset",
       "path": "assets/2205400862",
       "revisionId": "1",
       "revisionCreateTime": "2023-03-02T22:27:04.062164400Z",
       "assetId": "2205400862",
       "displayName": "Name",
       "description": "This is a description",
       "assetType": "ASSET_TYPE_DECAL",
       "creationContext": {
         "creator": {
           "userId": "11112938575"
         }
       },
       "moderationResult": {
         "moderationState": "MODERATION_STATE_APPROVED"
       }
     }
   }

3. (Optional) Check the created asset on your Roblox account.

   1. Navigate to the Inventory page of your Roblox account.
   2. Select the Category of the asset that you want to check.
   3. Find the target asset and click its thumbnail to view the asset.

Adding Assets API to OAuth 2.0 Apps

You can create OAuth 2.0 applications supporting Assets API to allow your users to upload and update assets to Roblox.

To use Assets API for your application and request permissions from your users, perform the following settings:

1. When registering your application, under Permissions, select asset:read and asset:write scopes.

2. When implementing the authorization flow, include asset:read and asset:write as the scope parameters of the authorization URL that redirects users back to your application, like the following example:

   https://www.authorize.roblox.com?client_id=819547628404595165403873012&redirect_uri=https://my-app.com/redirect&scope=asset:read+asset:write&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. When sending the request, include the access token in the authorization header and the form data of the asset content to create or update in the request URI in. The following example shows a sample request for uploading a new asset:

   Example Request
   curl --location --request POST 'https://apis.roblox.com/assets/v1/assets' \
   
   --header 'Authorization: Bearer <access_token>' \
   
   --header 'Content-Type: application/json' \
   
   --form 'request="{
   
     \"assetType\": \"Decal\",
   
     \"displayName\": \"DecalDemo123\",
   
     \"description\": \"This is a description\",
   
     \"creationContext\": {
   
       \"creator\": {
   
       \"userId\": \"<user_id>\"
   
       }
     }
   
   }"' \
   
   --form 'fileContent=@"/filepath/p1.png"'