Assets API

You can send and receive the following request and response payloads to create assets on Roblox. For information on the usage of the API, see the usage guide.

Assets

https://apis.roblox.com/assets

Create Asset

POST /v1/assets

Creates an asset with provided content and metadata.

You can't add SocialLink objects when you create an asset. Instead, use Update Asset.

Provide the Asset, binary asset file path, and content type in the form data.

Request

Create Asset
curl --location --request POST '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}\" 

    } 

  } 

}"' \

--form 'fileContent=@"/filepath/model.fbx";type=model/fbx'

Response

200 - OK
Returns the Operation ID for checking the creation status.
Returns an object
path string

The server-assigned resource path. The default format is operations/{operation_id}.

metadata object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

done boolean

If false, the operation is still in progress. If true, the operation is completed.

error object

The logical error model explaining the error status.

response object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

  • Write

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

  • asset:write

Limits

Per API Key: 60 requests every 60 seconds per IP Address

Get Asset

GET /v1/assets/{assetId}

Retrieve specific asset content and metadata.

Parameters

assetId string

The unique identifier of the asset.

Path
Required
readMask string

Asset metadata fields to retrieve, including the description, display name, icon, social links, and previews. Examples: description%2CdisplayName, previews%2CtwitchSocialLink.

Request

Get Asset without readMask
curl --location --request GET 'https://apis.roblox.com/assets/v1/assets/{assetId}' \

--header 'x-api-key: {apiKey}'
Get Asset with readMask
curl --location --request GET 'https://apis.roblox.com/assets/v1/assets/{assetId}?readMask={read_mask}' \

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

Response

200 - OK
Asset resource retrieved successfully.
Returns an object
assetType string

The asset type. Can only be Audio, Decal, or Model. Required for Create Asset.

assetId number

The unique identifier of the asset. Required for Update Asset.

creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

description string

The description of the asset. Limit to 1000 characters. Required for Create Asset.

displayName string

Display name of the asset. Required for Create Asset.

path string

The returned resource path of the asset. Format: assets/{assetId}. Example: assets/2205400862.

revisionId string

Revision ID of the asset. Equivalent to versionNumber. Every change of the asset automatically commits a new version. The format is an integer string. Example: 1.

revisionCreateTime string

The creation timestamp of the current revision.

moderationResult object

The moderation result of the asset.

icon string

The resource path for the icon.

previews array<object>

A list of previews, each with an asset path and alt text. Previews must be Image assets.

state string

Whether the asset is active or archived. Unspecified isn't used.

socialLink object

A social media link for the asset. Maximum of three per asset. Object name can be any of:

  • facebookSocialLink
  • twitterSocialLink
  • youtubeSocialLink
  • twitchSocialLink
  • discordSocialLink
  • githubSocialLink
  • robloxSocialLink
  • guildedSocialLink
  • devForumSocialLink
For syntax, see the sample request under Update Asset.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

Limits

Per API Key: 60 requests every 60 seconds per IP Address

Update Asset

PATCH /v1/assets/{assetId}

Updates an asset with provided content and metadata, including the description, display name, icon, social links, and previews. Currently can only update the content body for Models. Icons and Previews must be Image assets. Icons must have square dimensions.

Provide the Asset, binary asset file path, and content type in the form data.

Parameters

assetId string

The unique identifier of the asset.

Path
Required
updateMask string

Asset metadata fields to update, including the description, display name, icon, and previews. Examples: description%2CdisplayName, previews%2CtwitchSocialLink.

Request

Update Content Only and Create a New Version
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \

--header 'x-api-key: {apiKey}' \

--form 'request="{\"assetId\": {assetId} }"' \

--form 'fileContent="@\"{file-path}\""'
Update Content and Metadata
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=description%2CdisplayName' \

--header 'x-api-key: {apiKey}' \

--form 'request="{

    \"assetType\": \"{assetType}\",

    \"assetId\": {assetId},

    \"displayName\": \"{new display name}\",

    \"description\": \"{new description}\",    

    \"creationContext\": { 

        \"creator\": {

            \"userId\": {userId}

        },

        \"expectedPrice\":{expectedPrice}

    },

}"' \

--form 'fileContent=@\"{file-path}\"'
Update a List of Previews
curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=previews' \

--header 'x-api-key: {apiKey}' \

--form 'request="{\"assetId\": \"{assetId}\", \"previews\": [{\"asset\": \"assets/123\", \"altText\": \"Your alt text.\"}]}"'
Update Social Links

Response

200 - OK
Returns the Operation ID for checking the update status / Returns the updated metadata fields.
Returns an object
application/json
{"previews": [

  {"asset": "assets/123", "altText": "preview 1"},

  {"asset": "assets/456", "altText": "preview 2"}

]}
path string

The server-assigned resource path. The default format is operations/{operation_id}.

metadata object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

done boolean

If false, the operation is still in progress. If true, the operation is completed.

error object

The logical error model explaining the error status.

response object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

  • Write

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

  • asset:write

Limits

Per API Key: 60 requests every 60 seconds per IP Address

Archive Asset

POST /v1/assets/{assetId}:archive

Archives the asset. Archived assets disappear from the website and are no longer usable or visible in Roblox experiences, but you can restore them.

Parameters

assetId string

The unique identifier of the asset.

Path
Required

Request

Archive Asset
curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}:archive' \

--header 'x-api-key: {apiKey}' \

--header 'Content-Type: application/json'

Response

200 - OK
Asset archived succesfully successfully.
Returns an object
assetType string

The asset type. Can only be Audio, Decal, or Model. Required for Create Asset.

assetId number

The unique identifier of the asset. Required for Update Asset.

creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

description string

The description of the asset. Limit to 1000 characters. Required for Create Asset.

displayName string

Display name of the asset. Required for Create Asset.

path string

The returned resource path of the asset. Format: assets/{assetId}. Example: assets/2205400862.

revisionId string

Revision ID of the asset. Equivalent to versionNumber. Every change of the asset automatically commits a new version. The format is an integer string. Example: 1.

revisionCreateTime string

The creation timestamp of the current revision.

moderationResult object

The moderation result of the asset.

icon string

The resource path for the icon.

previews array<object>

A list of previews, each with an asset path and alt text. Previews must be Image assets.

state string

Whether the asset is active or archived. Unspecified isn't used.

socialLink object

A social media link for the asset. Maximum of three per asset. Object name can be any of:

  • facebookSocialLink
  • twitterSocialLink
  • youtubeSocialLink
  • twitchSocialLink
  • discordSocialLink
  • githubSocialLink
  • robloxSocialLink
  • guildedSocialLink
  • devForumSocialLink
For syntax, see the sample request under Update Asset.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

  • Write

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

  • asset:write

Limits

Per API Key: 100 requests every 60 seconds per IP Address

Restore Asset

POST /v1/assets/{assetId}:restore

Restores an archived asset.

Parameters

assetId string

The unique identifier of the asset.

Path
Required

Request

Restore Asset
curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}:restore' \

--header 'x-api-key: {apiKey}' \

--header 'Content-Type: application/json'

Response

200 - OK
Asset restored successfully.
Returns an object
assetType string

The asset type. Can only be Audio, Decal, or Model. Required for Create Asset.

assetId number

The unique identifier of the asset. Required for Update Asset.

creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

description string

The description of the asset. Limit to 1000 characters. Required for Create Asset.

displayName string

Display name of the asset. Required for Create Asset.

path string

The returned resource path of the asset. Format: assets/{assetId}. Example: assets/2205400862.

revisionId string

Revision ID of the asset. Equivalent to versionNumber. Every change of the asset automatically commits a new version. The format is an integer string. Example: 1.

revisionCreateTime string

The creation timestamp of the current revision.

moderationResult object

The moderation result of the asset.

icon string

The resource path for the icon.

previews array<object>

A list of previews, each with an asset path and alt text. Previews must be Image assets.

state string

Whether the asset is active or archived. Unspecified isn't used.

socialLink object

A social media link for the asset. Maximum of three per asset. Object name can be any of:

  • facebookSocialLink
  • twitterSocialLink
  • youtubeSocialLink
  • twitchSocialLink
  • discordSocialLink
  • githubSocialLink
  • robloxSocialLink
  • guildedSocialLink
  • devForumSocialLink
For syntax, see the sample request under Update Asset.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

  • Write

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

  • asset:write

Limits

Per API Key: 100 requests every 60 seconds per IP Address

Get Asset Version

GET /v1/assets/{assetId}/versions/{versionNumber}

Retrieve a specific asset version by the asset ID and the version number.

Parameters

assetId string

The unique identifier of the asset.

Path
Required
versionNumber string

The version number.

Path
Required

Request

Get Asset Version
curl --location 'https://apis.roblox.com/assets/v1/assets/{assetId}/versions/{versionNumber}' \

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

Response

200 - OK
Asset version retrieved successfully.
Returns an object
creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

path string

The returned resource path of the asset version. Format: assets/{assetId}/versions/{version}. Example: assets/2205400862/versions/1.

moderationResult object

The moderation result of the asset.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

Limits

Per API Key: 100 requests every 60 seconds per IP Address

List Asset Versions

GET /assets/v1/assets/{assetId}/versions

List all versions of a specific asset, with optional pagination.

Parameters

assetId string

The unique identifier of the asset.

Path
Required
maxPageSize number

Specifies the number of asset versions to include in the response. Valid values range from 1 to 50 (inclusive). Defaults to 8 when not provided.

pageToken string

A token for pagination. The value is obtained from a previous request and allows for retrieving the next page of asset versions.

Request

List Asset Versions
curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}/versions?pageToken=&maxPageSize=' \

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

Response

200 - OK
Asset versions listed successfully.
Returns an array<object>

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

Limits

Per API Key: 100 requests every 60 seconds per IP Address

Rollback Asset Version

POST /assets/v1/assets/{assetId}/versions:rollback

Rollback an asset to a specific previous version.

Provide the asset version path in the form data.

Parameters

assetId string

The unique identifier of the asset.

Path
Required

Request

Rollback Asset Versions
curl --location 'https://apis.roblox.com/assets/v1/assets/{assetid}/versions:rollback' \

--header 'x-api-key: {apiKey}' \

--header 'Content-Type: application/json' \

--data '{\"assetVersion\":\"assets/{assetId}/versions/{versionNumber}\"}'

Response

200 - OK
Asset rolled back successfully.
Returns an object
creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

path string

The returned resource path of the asset version. Format: assets/{assetId}/versions/{version}. Example: assets/2205400862/versions/1.

moderationResult object

The moderation result of the asset.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

  • Write

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

  • asset:write

Limits

Per API Key: 100 requests every 60 seconds per IP Address

Get Operation

GET /v1/operations/{operationId}

Get the result of an asset creation or update using the returned Operation ID. Requires Read for the API key permission and asset:read for OAuth 2.0 apps.

Parameters

operationId string

The unique identifier of the operation.

Path
Required

Request

Get Operation
curl --location 'https://apis.roblox.com/assets/v1/operations/{operationId}' \

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

Response

200 - OK
Operation result retrieved successfully.
Returns an object
path string

The server-assigned resource path. The default format is operations/{operation_id}.

metadata object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

done boolean

If false, the operation is still in progress. If true, the operation is completed.

error object

The logical error model explaining the error status.

response object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see App registration and review.

  • asset:read

Limits

Per API Key: 100 requests every 60 seconds per IP Address

Objects

The following objects describe payloads that are accepted or returned. See each individual endpoint for more information on when these objects are used.

Any

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Attributes

@type string

The type of the serialized message.

Asset

Represents an asset.

Attributes

assetType string

The asset type. Can only be Audio, Decal, or Model. Required for Create Asset.

assetId number

The unique identifier of the asset. Required for Update Asset.

creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

description string

The description of the asset. Limit to 1000 characters. Required for Create Asset.

displayName string

Display name of the asset. Required for Create Asset.

path string

The returned resource path of the asset. Format: assets/{assetId}. Example: assets/2205400862.

revisionId string

Revision ID of the asset. Equivalent to versionNumber. Every change of the asset automatically commits a new version. The format is an integer string. Example: 1.

revisionCreateTime string

The creation timestamp of the current revision.

moderationResult object

The moderation result of the asset.

icon string

The resource path for the icon.

previews array<object>

A list of previews, each with an asset path and alt text. Previews must be Image assets.

state string

Whether the asset is active or archived. Unspecified isn't used.

socialLink object

A social media link for the asset. Maximum of three per asset. Object name can be any of:

  • facebookSocialLink
  • twitterSocialLink
  • youtubeSocialLink
  • twitchSocialLink
  • discordSocialLink
  • githubSocialLink
  • robloxSocialLink
  • guildedSocialLink
  • devForumSocialLink
For syntax, see the sample request under Update Asset.

AssetVersion

An asset version.

Attributes

creationContext object

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

path string

The returned resource path of the asset version. Format: assets/{assetId}/versions/{version}. Example: assets/2205400862/versions/1.

moderationResult object

The moderation result of the asset.

CreationContext

The context of creation that is not part of the asset content, such as metadata and creator information. Required for Create Asset.

Attributes

creator object

Represents a creator.

Required
expectedPrice number

Expected asset upload fee in Robux. When the actual price is more than expected, the operation fails with a 400 error.

Creator

Represents a creator.

Attributes

userId number

The User ID the creator. Required if the asset is individual-user-owned.

groupId number

The Group ID. Required if the asset is group-owned.

ModerationResult

The moderation result of the asset.

Attributes

moderationState string

The moderation state of the asset. Can be Reviewing, Rejected, or Approved.

Operation

This resource represents a long-running operation that is the result of a network API call.

Attributes

path string

The server-assigned resource path. The default format is operations/{operation_id}.

metadata object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

done boolean

If false, the operation is still in progress. If true, the operation is completed.

error object

The logical error model explaining the error status.

response object

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Preview

An asset preview.

Attributes

asset string

The preview asset path.

altText string

Alt text for the preview asset.

A social media link for the asset. Maximum of three per asset. Object name can be any of:

  • facebookSocialLink
  • twitterSocialLink
  • youtubeSocialLink
  • twitchSocialLink
  • discordSocialLink
  • githubSocialLink
  • robloxSocialLink
  • guildedSocialLink
  • devForumSocialLink
For syntax, see the sample request under Update Asset.

Attributes

title string

An optional title for the social media link. Not used on the Creator Hub.

uri string

The URI for the social media link. Must match the expected format for the type of link. For example, the title for a twitchSocialLink object must be of the format https://twitch.tv/your-channel.

State

Whether the asset is active or archived. Unspecified isn't used.

Attributes

string (enum): "Unspecified", "Active", "Archived"

Status

The logical error model explaining the error status.

Attributes

code number

The HTTP status code.

message string

The error message.

details array<object>

A list of messages carrying error details.