> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://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 media 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 custom metadata for the knowledge store item. Keys are strings; each value is a string, a number, a boolean, or an array of strings.
* `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.

## 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"
  },
  "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"
  },
  "created_at": "2026-05-12T16:53:59Z",
  "updated_at": "2026-05-12T16:55:59Z"
}
```

> Knowledge store item object schema.