> 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.

# Knowledge stores

> A persistent, queryable store of your videos and images plus the understanding the platform derives from them.

A knowledge store is a persistent, queryable store of your videos and images plus the understanding the platform derives from them. It contains three layers:

* **Spatiotemporal context**: entities, moments, facts, and summaries extracted from your videos and images
* **Typed ontology**: a schema that organizes those elements and their relationships
* **Embeddings**: vector representations that make the content semantically retrievable

Together these layers form the foundation for corpus-level reasoning: the platform reasons across the full collection, not just individual clips.

# Ingestion configuration

The ingestion configuration controls what the platform extracts from your videos and images. Set it when you create a knowledge store.

For the available approaches and guidance on choosing one, see the [Configure ingestion](/v1.3/agents/guides/create-a-knowledge-store/configure-ingestion) guide.

# Knowledge store items

A knowledge store item is an asset added to a knowledge store for indexing. Items are processed asynchronously.

```
Add asset → queued → pending → processing → ready
                                          → failed
```

| Status       | Meaning                    | Action                             |
| ------------ | -------------------------- | ---------------------------------- |
| `queued`     | Waiting to be processed    | Poll and wait                      |
| `pending`    | About to start processing  | Poll and wait                      |
| `processing` | Indexing in progress       | Poll and wait                      |
| `ready`      | Item indexed and queryable | Proceed to query                   |
| `failed`     | Indexing failed            | Check error, retry with a new item |

All items must reach the `ready` status before queries return meaningful results. Each query targets a single knowledge store. You cannot query across stores.

# 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)

# API reference

* [POST /knowledge-stores](/v1.3/api-reference/knowledge-stores/create) - create a knowledge store
* [GET /knowledge-stores/\{id}](/v1.3/api-reference/knowledge-stores/retrieve) - retrieve a knowledge store
* [POST /knowledge-stores/\{id}/items](/v1.3/api-reference/knowledge-store-items/create) - add an item
* [GET /knowledge-stores/\{id}/items/\{item\_id}](/v1.3/api-reference/knowledge-store-items/retrieve) - check item status