---
title: "Update the user-defined metadata of an asset"
method: PATCH
path: "/assets/{asset_id}/user-metadata"
tags: ["assets"]
---

# Update the user-defined metadata of an asset

`PATCH /assets/{asset_id}/user-metadata`

This method updates the user-defined metadata of the specified asset. The platform merges your changes with the existing metadata:
- A key with a value creates or replaces that key.
- A key set to `null` deletes that key.
- A key set to an empty string (`""`) is ignored.
- A key you omit from the request keeps its current value.

To replace all metadata in a single call, use the [`PUT`](/v1.3/api-reference/upload-content/direct-uploads/replace-user-metadata) method of the `/assets/{asset_id}/user-metadata` endpoint instead.

## Path parameters

- `asset_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- object
  - `user_metadata` UserMetadata, required — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>

## Response `200`

Successful response

## Other responses

- `400` — The request has failed.
- `404` — The specified resource does not exist.

## Changes

- **2026-07-31** `5dbd6e8473c9` — 1 warning
  - removed the optional property `docs_url` from the response with the `400` status
- **2026-07-26** `c0926990c662` — 1 breaking, 1 info
  - removed the success response with the status `204`
  - added the success response with the status `200`

[Change history](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/changes/assets/:asset_id/user-metadata/patch.md)

---

[API](https://skmtc.dev/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/03b6cc37a537/schema)