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

# Quickstart

> Get started with the Agents platform. Generate a response from a knowledge store, or search it with a natural-language query.

Jockey reasons across your videos and images and answers with grounded, cited moments. This page takes you from nothing to a first result through the API.

First you put your videos and images in a [knowledge store](/v1.3/agents/concepts/knowledge-stores), a collection that [Jockey](/v1.3/agents/concepts/jockey) can search and reason across. That setup is the same every time. Then you choose how to get something back from it:

* **Search a knowledge store** when you know what you are looking for. You describe it in plain language, and you receive the matching clips and images, ranked by how well they match. Nothing is interpreted or summarized, so you can show the results in your app or pass them to your own code.
* **Create a response** when you have a question. Jockey plans its own steps, searches and reasons across everything in the knowledge store, and writes an answer that cites the moments it used.

Both work on the same knowledge store, so you can use one and then the other without uploading anything again.

4 steps, Python or Node.js

1. 1Create a keyFree account
2. 2InstallOne command
3. 3RunChoose a response or a search
4. 4Read resultsCited moments, or ranked clips

> **Prefer not to write code?**
>
> You can use Jockey without writing code. [Start with the Jockey MCP](/v1.3/agents/get-started/start-with-jockey) connects it to Claude or ChatGPT in four steps, and you can ask questions about your videos right in the chat. The knowledge stores Jockey uses are also visible in [Connect](https://connect.twelvelabs.io), where you can manage them.

#### Get an API key

[Sign up](https://playground.twelvelabs.io/) for a free account, open the [API Keys](https://playground.twelvelabs.io/dashboard/api-keys) page, and create and copy a key.

#### Install the SDK

**`Python`**

```shell Python
pip install --upgrade twelvelabs
```

**`Node.js`**

```shell Node.js
npm install twelvelabs-js@latest
```

#### Choose what you want to do and run its code

Both tabs start with the same setup: the starter code uploads your content, builds a knowledge store, and waits until it is ready. They differ only in the last request.

Public video URLs can be up to 4 GB, local videos up to 200 MB, and images up to 32 MB. Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported. Use a short clip for your first run.

Choose the tab that matches what you want back, then fill in the values in angle brackets, such as your API key and a link to your video, and run it.

| If you want                                                          | Choose                   | You receive                                   |
| -------------------------------------------------------------------- | ------------------------ | --------------------------------------------- |
| The matching moments themselves, to show or process in your own code | Search a knowledge store | Clips and images, ranked by relevance         |
| An answer to a question about your content                           | Create a response        | Written text with the cited moments behind it |

#### Create a response

**Ask a question.** Jockey searches and reasons across your content, then answers in text and cites the moments it used.

**`Python`**

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

# Step 1: Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Step 2: Upload a video or an image
asset = client.assets.create(method="url", url="<YOUR_MEDIA_URL>")  # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
# Or use method="direct" and file=open("<YOUR_FILE_PATH>", "rb") to upload a local file up to 200 MB
print(f"Asset created: {asset.id}")

# Step 3: Check the status of the asset
while True:
    status = client.assets.retrieve(asset_id=asset.id).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Asset processing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(5)
print("Asset ready")

# Step 4: Create a knowledge store
store = client.knowledge_stores.create(name="<YOUR_KNOWLEDGE_STORE_NAME>")
print(f"Knowledge store created: {store.id}")

# Step 5: Add the asset to the knowledge store
item = client.knowledge_store_items.create(
    knowledge_store_id=store.id,
    asset_id=asset.id,
    # asset_type="image",  # Uncomment if your asset is an image (the default is video)
)
print(f"Item added: {item.id}")

# Step 6: 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")

# Step 7: Generate a response
response = client.responses.create(
    knowledge_store_id=store.id,
    input=[{"type": "message", "role": "user", "content": "Give me an overview of this content - main themes, key subjects, and any patterns."}],
)
for output in response.output:
    if output.type == "message":
        for content in output.content:
            print(content.text)
```

**`Node.js`**

```javascript Node.js maxlines=40
import { TwelveLabs } from "twelvelabs-js";
// Uncomment the next line if uploading a local file
// import fs from "fs";

// Step 1: Initialize the client
const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Step 2: Upload a video or an image
const asset = await client.assets.create({ method: "url", url: "<YOUR_MEDIA_URL>" }); // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
// Or use method: "direct" and file: fs.createReadStream("<YOUR_FILE_PATH>") to upload a local file up to 200 MB
console.log(`Asset created: ${asset.id}`);

// Step 3: Check the status of the asset
while (true) {
  const { status } = await client.assets.retrieve(asset.id);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Asset processing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
}
console.log("Asset ready");

// Step 4: Create a knowledge store
const store = await client.knowledgeStores.create({ name: "<YOUR_KNOWLEDGE_STORE_NAME>" });
console.log(`Knowledge store created: ${store.id}`);

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

// Step 6: Check the status of the knowledge store item
while (true) {
  const { status } = await client.knowledgeStoreItems.retrieve(store.id, 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");

// Step 7: Generate a response
const response = await client.responses.create({
  knowledgeStoreId: store.id,
  input: [{ type: "message", role: "user", content: "Give me an overview of this content - main themes, key subjects, and any patterns." }],
});
for (const output of response.output ?? []) {
  if (output.type === "message") {
    for (const content of output.content ?? []) {
      console.log(content.text);
    }
  }
}
```

#### Search a knowledge store

**Search in plain language.** Receive the video clips and images that match your query, ranked by relevance, with no interpretation added.

**`Python`**

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

# Step 1: Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Step 2: Upload a video or an image
asset = client.assets.create(method="url", url="<YOUR_MEDIA_URL>")  # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
# Or use method="direct" and file=open("<YOUR_FILE_PATH>", "rb") to upload a local file up to 200 MB
print(f"Asset created: {asset.id}")

# Step 3: Check the status of the asset
while True:
    status = client.assets.retrieve(asset_id=asset.id).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Asset processing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(5)
print("Asset ready")

# Step 4: Create a knowledge store
store = client.knowledge_stores.create(name="<YOUR_KNOWLEDGE_STORE_NAME>")
print(f"Knowledge store created: {store.id}")

# Step 5: Add the asset to the knowledge store
item = client.knowledge_store_items.create(
    knowledge_store_id=store.id,
    asset_id=asset.id,
    # asset_type="image",  # Uncomment if your asset is an image (the default is video)
)
print(f"Item added: {item.id}")

# Step 6: 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")

# Step 7: Search the knowledge store
result = client.knowledge_stores.search(
    knowledge_store_id=store.id,
    query={"text": "<YOUR_QUERY>"},
    search_options={"video": {"modalities": ["visual", "audio"]}},
)
for hit in result.data:
    if hit.asset_type == "video":
        clip = hit.matches[0]
        print(f"Rank {hit.rank}: video {hit.item_id}  {clip.start_sec}s-{clip.end_sec}s")
    elif hit.asset_type == "image":
        print(f"Rank {hit.rank}: image {hit.item_id}")
```

**`Node.js`**

```javascript Node.js maxlines=38
import { TwelveLabs } from "twelvelabs-js";
// Uncomment the next line if uploading a local file
// import fs from "fs";

// Step 1: Initialize the client
const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Step 2: Upload a video or an image
const asset = await client.assets.create({ method: "url", url: "<YOUR_MEDIA_URL>" }); // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
// Or use method: "direct" and file: fs.createReadStream("<YOUR_FILE_PATH>") to upload a local file up to 200 MB
console.log(`Asset created: ${asset.id}`);

// Step 3: Check the status of the asset
while (true) {
  const { status } = await client.assets.retrieve(asset.id);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Asset processing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
}
console.log("Asset ready");

// Step 4: Create a knowledge store
const store = await client.knowledgeStores.create({ name: "<YOUR_KNOWLEDGE_STORE_NAME>" });
console.log(`Knowledge store created: ${store.id}`);

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

// Step 6: Check the status of the knowledge store item
while (true) {
  const { status } = await client.knowledgeStoreItems.retrieve(store.id, 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");

// Step 7: Search the knowledge store
const result = await client.knowledgeStores.search(store.id, {
  query: { text: "<YOUR_QUERY>" },
  searchOptions: { video: { modalities: ["visual", "audio"] } },
});
for (const hit of result.data ?? []) {
  if (hit.assetType === "video") {
    const clip = hit.matches[0];
    console.log(`Rank ${hit.rank}: video ${hit.itemId}  ${clip.startSec}s-${clip.endSec}s`);
  } else if (hit.assetType === "image") {
    console.log(`Rank ${hit.rank}: image ${hit.itemId}`);
  }
}
```

#### Read your results

When your code finishes, it prints the result of what you chose:

* **Create a response:** Jockey's answer to your question, as text.
* **Search a knowledge store:** one line for each match, with its rank, its item identifier, and for a video, the start and end times of the clip.

Longer content takes longer to become ready.

# A few terms

* **Asset**: a file you uploaded. You can reuse it without uploading it again.
* **Knowledge store**: a collection of your videos and images that Jockey can search and reason across.
* **Knowledge store item**: an asset that you added to a knowledge store. It is ready to use when its status is `ready`.

# Next steps

Each task has a full quickstart with an explanation of every part of the code, and the recipes show what else Jockey can do.

#### [Create a response quickstart](/v1.3/agents/get-started/quickstart/create-a-response)

A full walkthrough of asking Jockey a question.

#### [Search quickstart](/v1.3/agents/get-started/quickstart/search-a-knowledge-store)

A full walkthrough of searching a knowledge store.

#### [Recipes](/v1.3/agents/recipes)

Ready-made tasks like highlight reels, agentic search, and organizing a video library.

#### [Migrating from Models?](/v1.3/agents/get-started/migrate-from-models)

Compare the two approaches and move your workflows.

For more in-depth information on each task, see the guides:

* [Create a response](/v1.3/agents/guides/create-a-response)
* [Search a knowledge store](/v1.3/agents/guides/search-a-knowledge-store)

If you are an AI agent building on Jockey, fetch the complete single-file, copy-paste integration guide as Markdown at [https://docs.twelvelabs.io/agents/agents.md](https://docs.twelvelabs.io/agents/agents.md) and read it before writing code. It covers the full knowledge-store to response/search loop, task recipes, and gotchas.