PATCH /assets/v1/assets/{assetId} — openapi

Updates an asset with provided content and metadata.

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.

Endpoint

Method: PATCH

Path: /assets/v1/assets/{assetId}

Servers:

https://apis.roblox.com

Parameters

Name	Location	Required	Description
assetId	path	true	The unique identifier of the asset.
updateMask	query	false	Asset metadata fields to update, including the description, display name, icon, and previews. Examples: `description%2CdisplayName`, `previews%2CtwitchSocialLink`.

[
  {
    "name": "assetId",
    "in": "path",
    "description": "The unique identifier of the asset.",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "updateMask",
    "in": "query",
    "required": false,
    "description": "Asset metadata fields to update, including the description, display name, icon, and previews. Examples: `description%2CdisplayName`, `previews%2CtwitchSocialLink`.",
    "schema": {
      "type": "string"
    }
  }
]

Request Body

{
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "properties": {
          "request": {
            "$ref": "#/components/schemas/Asset",
            "description": "Asset attributes to update."
          },
          "fileContent": {
            "type": "string",
            "format": "binary",
            "description": "The binary asset file path and the content type. See [Asset types and limits](/cloud/guides/usage-assets.md#supported-asset-types-and-limits)."
          }
        },
        "required": [
          "request",
          "fileContent"
        ]
      }
    }
  }
}

Responses

Status	Description
200	Returns the Operation ID for checking the update status / Returns the updated metadata fields.
400	Invalid argument. Failed to parse the request or the file.
401	The API key is not valid for this operation / You don't have the authorization.
500	Server internal error / Unknown error.

{
  "200": {
    "description": "Returns the Operation ID for checking the update status / Returns the updated metadata fields.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OCV1.Assets.Operation",
          "example": "{\"previews\": [\n  {\"asset\": \"assets/123\", \"altText\": \"preview 1\"},\n  {\"asset\": \"assets/456\", \"altText\": \"preview 2\"}\n]}"
        }
      }
    }
  },
  "400": {
    "description": "Invalid argument. Failed to parse the request or the file.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OCV1.Assets.Status"
        }
      }
    }
  },
  "401": {
    "description": "The API key is not valid for this operation / You don't have the authorization."
  },
  "500": {
    "description": "Server internal error / Unknown error."
  }
}

Authentication

{
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "securitySchemes": {
    "roblox-api-key": {
      "type": "apiKey",
      "description": "A configurable key that allows granular access to Roblox resources. See https://create.roblox.com/docs/cloud/auth/api-keys for more information.",
      "name": "x-api-key",
      "in": "header"
    },
    "roblox-legacy-cookie": {
      "type": "apiKey",
      "description": "A browser cookie that represents the identity of a Roblox user. DO NOT SHARE THIS. Sharing this will allow someone to log in as you and to steal your Robux and items. We do not recommend using cookies to call endpoints. When possible, use API keys with the x-api-key header or OAuth 2.0 instead for authentication.",
      "in": "cookie",
      "name": ".ROBLOSECURITY"
    },
    "roblox-oauth2": {
      "type": "oauth2",
      "description": "Build or authorize apps to access Roblox resources. See https://create.roblox.com/docs/cloud/auth/oauth2-overview for more information.",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://apis.roblox.com/oauth/v1/authorize",
          "tokenUrl": "https://apis.roblox.com/oauth/v1/token",
          "refreshUrl": "https://apis.roblox.com/oauth/v1/token",
          "scopes": {}
        }
      }
    }
  }
}

Complete Operation Definition

{
  "tags": [
    "Assets"
  ],
  "x-roblox-cloud-api-operation": true,
  "x-roblox-cloud-api-operation-name": "Update Asset",
  "x-roblox-stability": "BETA",
  "summary": "Updates an asset with provided content and metadata.",
  "description": "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.\n\nProvide the [Asset](#Asset), binary asset file path, and [content type](/cloud/guides/usage-assets.md#supported-asset-types-and-limits) in the form data.",
  "operationId": "Assets_UpdateAsset",
  "parameters": [
    {
      "name": "assetId",
      "in": "path",
      "description": "The unique identifier of the asset.",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "updateMask",
      "in": "query",
      "required": false,
      "description": "Asset metadata fields to update, including the description, display name, icon, and previews. Examples: `description%2CdisplayName`, `previews%2CtwitchSocialLink`.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "properties": {
            "request": {
              "$ref": "#/components/schemas/Asset",
              "description": "Asset attributes to update."
            },
            "fileContent": {
              "type": "string",
              "format": "binary",
              "description": "The binary asset file path and the content type. See [Asset types and limits](/cloud/guides/usage-assets.md#supported-asset-types-and-limits)."
            }
          },
          "required": [
            "request",
            "fileContent"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Returns the Operation ID for checking the update status / Returns the updated metadata fields.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/OCV1.Assets.Operation",
            "example": "{\"previews\": [\n  {\"asset\": \"assets/123\", \"altText\": \"preview 1\"},\n  {\"asset\": \"assets/456\", \"altText\": \"preview 2\"}\n]}"
          }
        }
      }
    },
    "400": {
      "description": "Invalid argument. Failed to parse the request or the file.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/OCV1.Assets.Status"
          }
        }
      }
    },
    "401": {
      "description": "The API key is not valid for this operation / You don't have the authorization."
    },
    "500": {
      "description": "Server internal error / Unknown error."
    }
  },
  "security": [
    {
      "roblox-api-key": []
    },
    {
      "roblox-oauth2": []
    }
  ],
  "x-roblox-scopes": [
    {
      "name": "asset:read"
    },
    {
      "name": "asset:write"
    }
  ],
  "x-roblox-cloud-api-operation-code-samples": [
    {
      "language": "Update Content Only and Create a New Version",
      "script": "curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}' \\\n--header 'x-api-key: {apiKey}' \\\n--form 'request=\"{\\\"assetId\\\": {assetId} }\"' \\\n--form 'fileContent=\"@\\\"{file-path}\\\"\"'"
    },
    {
      "language": "Update Content and Metadata",
      "script": "curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=description%2CdisplayName' \\\n--header 'x-api-key: {apiKey}' \\\n--form 'request=\"{\n    \\\"assetType\\\": \\\"{assetType}\\\",\n    \\\"assetId\\\": {assetId},\n    \\\"displayName\\\": \\\"{new display name}\\\",\n    \\\"description\\\": \\\"{new description}\\\",    \n    \\\"creationContext\\\": { \n        \\\"creator\\\": {\n            \\\"userId\\\": {userId}\n        },\n        \\\"expectedPrice\\\":{expectedPrice}\n    },\n}\"' \\\n--form 'fileContent=@\\\"{file-path}\\\"'"
    },
    {
      "language": "Update a List of Previews",
      "script": "curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=previews' \\\n--header 'x-api-key: {apiKey}' \\\n--form 'request=\"{\\\"assetId\\\": \\\"{assetId}\\\", \\\"previews\\\": [{\\\"asset\\\": \\\"assets/123\\\", \\\"altText\\\": \\\"Your alt text.\\\"}]}\"'"
    },
    {
      "language": "Update Social Links",
      "script": "curl --location --request PATCH 'https://apis.roblox.com/assets/v1/assets/{assetId}?updateMask=twitchSocialLink%2CgithubSocialLink' \\\n--header 'x-api-key: {apiKey}' \\\n--form 'request=\"{\\\"assetId\\\": \\\"{assetId}\\\", \\\"twitchSocialLink\\\": {\\\"title\\\": \\\"Optional title\\\", \\\"uri\\\": \\\"https://twitch.tv/your-channel\\\"}, \\\"githubSocialLink\\\": {\\\"title\\\": \\\"Optional title\\\", \\\"uri\\\": \\\"https://github.com/your-repo\\\"}}\"'"
    }
  ],
  "x-roblox-rate-limits": {
    "perApiKeyOwner": {
      "period": "MINUTE",
      "maxInPeriod": 120
    },
    "perOauth2Authorization": {
      "period": "MINUTE",
      "maxInPeriod": 120
    }
  },
  "x-roblox-engine-usability": {
    "apiKeyWithHttpService": true
  },
  "externalDocs": {
    "url": "https://create.roblox.com/docs/cloud/reference/features/assets#Assets_UpdateAsset"
  }
}