Replace the item metadata

curl -X PUT https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items/ksi_069e9870-3c4d-7abc-9012-3456789abcde/item-metadata \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "item_metadata": {
    "creator_handle": "@jane.doe",
    "view_count": 48210
  }
}'

{
  "asset_type": "video",
  "_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
  "asset_id": "6298d673f1090f1100476d4c",
  "status": "ready",
  "system_metadata": {
    "asset_type": "video",
    "codec_name": "h264",
    "duration": 531.998133,
    "filename": "01.mp4",
    "fps": 29.97,
    "height": 1080,
    "size": 65749715,
    "width": 1920
  },
  "metadata": {},
  "item_metadata": {
    "creator_handle": "@jane.doe",
    "view_count": 48210
  },
  "enriched_metadata": {
    "brand": "Acme"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

This method replaces the entire item_metadata of the specified knowledge store item and returns the item. Unlike the PATCH method, which merges your changes with the existing metadata, this method overwrites the stored value in full:

A key with a value creates or replaces that key.
A key you omit, or set to an empty string (""), an empty array ([]), or null, is removed.

To clear all item metadata, send an empty object ({}) in the item_metadata field. The metadata field of the item does not change.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Path parameters

knowledge_store_idstringRequired

The unique identifier of the knowledge store.

item_idstringRequired

The unique identifier of the knowledge store item.

Request

This endpoint expects an object.

item_metadatamap from strings to nullable strings or integers or doubles or booleans or lists of stringsRequired

The complete item_metadata of the item after the request. Up to 50 pairs. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, or an array of strings. A nested object and an array containing anything other than strings are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string.

Response

The item metadata has been successfully replaced.

asset_typeenum

The type of item.

Allowed values:

_idstringOptional

The unique identifier of the knowledge store item.

asset_idstringOptional

The unique identifier of the source asset.

statusenumOptionalRead-only

The processing status of the item. For the meaning of each value, see the Item statuses section on The knowledge store item object page.

Allowed values:

system_metadataobjectOptionalRead-only

System-generated metadata for the source asset. Its asset_type field always matches the item’s top-level asset_type field.

metadatamap from strings to strings or integers or doubles or booleans or lists of stringsOptional

The custom metadata of the source asset. Keys are strings; each value is a string, a number, a boolean, or an array of strings. The platform updates it when the user-defined metadata of the asset changes. To change it, use the PATCH method of the /assets/{asset_id}/user-metadata endpoint. To set custom metadata for the knowledge store item only, use item_metadata.

item_metadatamap from strings to strings or integers or doubles or booleans or lists of stringsOptional

The custom metadata of the knowledge store item. Keys are strings; each value is a string, a number, a boolean, or an array of strings. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the metadata field and in the item_metadata field. You set it when you create the item or change it with the PATCH or PUT method of the /knowledge-stores/{knowledge_store_id}/items/{item_id}/item-metadata endpoint. This field is absent when no item metadata has been set.

enriched_metadatamap from strings to anyOptionalRead-only

Metadata that the platform extracts from the whole item, as defined by the enrichment configuration of the knowledge store. It contains the properties that have the granularity keyword set to video for a video, or to image for an image. Properties that have the granularity keyword set to shot do not appear in this field. Keys are the property names; each value matches its property definition. A property with no value is omitted. The field is present only when the item is ready and contains at least one value.

created_atstringOptionalformat: "date-time"

The date and time when the item was created, in the RFC 3339 format.

updated_atstringOptionalformat: "date-time"

The date and time when the item was last updated, in the RFC 3339 format.

Errors

400

Bad Request Error

404

Not Found Error

422

Unprocessable Entity Error