> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta.docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server. # The knowledge store item object > Knowledge store item object schema. A knowledge store item is an asset added to a knowledge store for processing. You can use it in different workflows once its `status` is `ready`. The object is composed of the following fields: * `_id`: A string representing the unique identifier of the knowledge store item. * `asset_type`: A string indicating the type of item. It can take one of the following values: * `video`: A video item. * `image`: An image item. * `asset_id`: A string representing the unique identifier of the source asset. * `status`: A string indicating the processing status of the item. See the [Item statuses](#item-statuses) section for the meaning of each value. * `system_metadata`: An object containing system-generated metadata for the source asset. The shape of this object depends on the value of the `asset_type` field. For the full structure, see the [`system_metadata`](/v1.3/api-reference/knowledge-store-items/retrieve#response.body.system_metadata) field on the **Retrieve a knowledge store item** page. * `metadata`: An object containing 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`](/v1.3/api-reference/upload-content/direct-uploads/update-user-metadata) method of the `/assets/{asset_id}/user-metadata` endpoint. To set custom metadata for the knowledge store item only, use `item_metadata`. * `item_metadata`: An object containing 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`](/v1.3/api-reference/knowledge-store-items/update-item-metadata) or [`PUT`](/v1.3/api-reference/knowledge-store-items/replace-item-metadata) 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_metadata`: An object containing 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_at`: A string representing the date and time, in the RFC 3339 format, when the item was created. * `updated_at`: A string representing the date and time, in the RFC 3339 format, when the item was last updated. ## Item statuses The `status` field of a knowledge store item has one of the following values: * `queued`: The item has been submitted and is waiting to be processed. * `pending`: The item has been dispatched and is waiting for available processing capacity. * `processing`: The item is being processed. * `ready`: The item has been successfully processed. * `failed`: The item processing has failed. ## Custom metadata field names A knowledge store item has two sets of custom metadata: the custom metadata of the source asset and the custom metadata of the knowledge store item. The table shows the name of each set in each place. | Place | Custom metadata of the source asset | Custom metadata of the knowledge store item | | :--------------------------------------------------------------------------------------------- | :---------------------------------- | :------------------------------------------ | | Key in the `filter` parameter of a search request | `user_metadata` | `user_metadata` | | Field of the knowledge store item | `metadata` | `item_metadata` | | Field of the `metadata` object in a search result (returned when `include_metadata` is `true`) | `user` | `item` | A `user_metadata` key in a search filter matches the value in either set. ## Examples Each example shows a populated knowledge store item. #### Video ```json { "_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde", "asset_type": "video", "asset_id": "6298d673f1090f1100476d4c", "status": "ready", "system_metadata": { "asset_type": "video", "filename": "01.mp4", "duration": 531.998133, "fps": 29.97, "width": 1920, "height": 1080, "codec_name": "h264", "size": 65749715 }, "metadata": { "project": "Q1 review" }, "item_metadata": { "reviewer": "jane" }, "enriched_metadata": { "brand": "Acme" }, "created_at": "2026-05-12T16:53:59Z", "updated_at": "2026-05-12T16:55:59Z" } ``` #### Image ```json { "_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcdf", "asset_type": "image", "asset_id": "6298d673f1090f1100476d4d", "status": "ready", "system_metadata": { "asset_type": "image", "filename": "01.jpg", "width": 1920, "height": 1080, "codec_name": "jpeg", "size": 204800 }, "metadata": { "project": "Q1 review" }, "item_metadata": { "reviewer": "jane" }, "created_at": "2026-05-12T16:53:59Z", "updated_at": "2026-05-12T16:55:59Z" } ```