> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Add assets to a knowledge store

This guide shows you how to add an uploaded asset to a knowledge store and wait for indexing to complete.

# Key concepts

* **Asset**: Your uploaded content. Once created, you can reference the same asset across multiple operations without uploading the file again.
* **Knowledge store**: A persistent store of your videos and images plus the understanding the platform derives from them - spatiotemporal context, a typed ontology, and embeddings - that together enable corpus-level reasoning.
* **Knowledge store item**: An asset added to a knowledge store. The platform processes each item asynchronously. When the item reaches the `ready` status, you can use it in downstream tasks.

# Prerequisites

* You've already uploaded your content, and the asset has reached the `ready` status. See the [Upload content](/v1.3/agents/guides/upload-content) page for details.
* You've already created a knowledge store. See the [Create a knowledge store](/v1.3/agents/guides/create-a-knowledge-store) page for details.

# Example

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```python Python maxlines=25
from twelvelabs import TwelveLabs
import time

client = TwelveLabs(api_key="<YOUR_API_KEY>")
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"

# Step 1: Add the asset to the knowledge store
item = client.knowledge_store_items.create(
    knowledge_store_id=STORE_ID,
    asset_id="<YOUR_ASSET_ID>",
    # asset_type="image",  # Uncomment to add an image (the default is video)
)
print(f"Item added: {item.id}")

# Step 2: Check the status of the knowledge store item
while True:
    status = client.knowledge_store_items.retrieve(
        knowledge_store_id=STORE_ID, item_id=item.id
    ).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Indexing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(10)
print("Indexing complete")
```

**`Node.js`**

```javascript Node.js maxlines=25
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });
const storeId = "<YOUR_KNOWLEDGE_STORE_ID>";

// Step 1: Add the asset to the knowledge store
const item = await client.knowledgeStoreItems.create(storeId, {
  assetId: "<YOUR_ASSET_ID>",
  // assetType: "image", // Uncomment to add an image (the default is video)
});
console.log(`Item added: ${item.id}`);

// Step 2: Check the status of the knowledge store item
while (true) {
  const { status } = await client.knowledgeStoreItems.retrieve(storeId, item.id);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Indexing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 10000));
}
console.log("Indexing complete");
```

# Code explanation

#### Python

#### Add the asset to the knowledge store

Add an uploaded asset to a knowledge store as an item. The platform begins indexing the item asynchronously. This example prints the item identifier to the standard output.\

**Function call**: You call the [`knowledge_store_items.create`](/v1.3/sdk-reference/python/knowledge-store-items#create-a-knowledge-store-item) method.\

**Parameters**:

* `knowledge_store_id`: The unique identifier of the knowledge store.
* `asset_id`: The unique identifier of the asset to add.
* *(Optional)* `asset_type`: The type of asset. Defaults to `video`; set it to `image` to add an image asset.\


**Return value**: An object of type `KnowledgeStoreItem` with the following fields:\


* `id`: The unique identifier of the newly created knowledge store item
* `file_type`: The type of the file the platform detected during upload
* `status`: The current status of the knowledge store item.

#### Check the status of the knowledge store item

Poll the item until it reaches the `ready` status. Indexing usually takes longer than the asset processing that happens after upload. One asset can exist in multiple knowledge stores. For the full list of statuses, see the [Knowledge stores](/v1.3/agents/concepts/knowledge-stores) page.\

**Function call**: You call the [`knowledge_store_items.retrieve`](/v1.3/sdk-reference/python/knowledge-store-items#retrieve-a-knowledge-store-item) method.\

**Parameters**:

* `knowledge_store_id`: The unique identifier of the knowledge store.
* `item_id`: The unique identifier of the knowledge store item, from the previous step.\


**Return value**: An object of type `KnowledgeStoreItem`. Check the `status` field for the current state.

#### Node.js

#### Add the asset to the knowledge store

Add an uploaded asset to a knowledge store as an item. The platform begins indexing the item asynchronously. This example prints the item identifier to the standard output.\

**Function call**: You call the [`knowledgeStoreItems.create`](/v1.3/sdk-reference/node-js/knowledge-store-items#create-a-knowledge-store-item) method.\

**Parameters**: You pass the knowledge store identifier as the first argument and the remaining parameters as properties of a second object.

* `knowledgeStoreId`: The unique identifier of the knowledge store.
* `assetId`: The unique identifier of the asset to add.
* *(Optional)* `assetType`: The type of asset. Defaults to `video`; set it to `image` to add an image asset.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `KnowledgeStoreItem` with the following fields:\


* `id`: The unique identifier of the newly created knowledge store item
* `fileType`: The type of the file the platform detected during upload
* `status`: The current status of the knowledge store item.

#### Check the status of the knowledge store item

Poll the item until it reaches the `ready` status. Indexing usually takes longer than the asset processing that happens after upload. One asset can exist in multiple knowledge stores. For the full list of statuses, see the [Knowledge stores](/v1.3/agents/concepts/knowledge-stores) page.\

**Function call**: You call the [`knowledgeStoreItems.retrieve`](/v1.3/sdk-reference/node-js/knowledge-store-items#retrieve-a-knowledge-store-item) method.\

**Parameters**: You pass the knowledge store identifier and the item identifier as arguments.

* `knowledgeStoreId`: The unique identifier of the knowledge store.
* `itemId`: The unique identifier of the knowledge store item, from the previous step.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `KnowledgeStoreItem`. Check the `status` field for the current state.

# Next steps

* [Create a response](/v1.3/agents/guides/create-a-response) - generate responses from your video and image collection through the Responses API
* [Search a knowledge store](/v1.3/agents/guides/search-a-knowledge-store) - find matching video clips and images in your knowledge store

# Jupyter notebook

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/guides/building_knowledge_stores.ipynb)