> 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. # Knowledge store items > Add items to a knowledge store, tag moments of video items, and organize items into collections with the Node.js SDK. Use these methods to add assets to a knowledge store as items, to tag moments and ranges of video items, and to organize items into named collections. # Knowledge store items The `KnowledgeStoreItems` class provides methods to add and manage the items in a knowledge store. ## Create a knowledge store item **Description**: This method adds an asset to a knowledge store for processing. The operation is asynchronous. The item is created immediately with the `queued` status and processed in the background. **Asset size limits**: * **Video**: Up to 10 GB * **Images**: Up to 32 MB **Function signature and example**: **`Function signature`** ```javascript Function signature create( knowledgeStoreId: string, request: TwelvelabsApi.KnowledgeStoreItemsCreateRequest, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const item = await client.knowledgeStoreItems.create("", { assetId: "", // assetType: "video", // itemMetadata: { team: "qa" }, }); console.log(`ID: ${item.id} Status: ${item.status}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :---------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `assetId` | `string` | Yes | The unique identifier of the asset to add to the knowledge store. If you uploaded the asset before your plan moved to the new billing, enable storage accounting for it before you add it to a knowledge store. Use [`assets.enableStorageAccounting`](/v1.3/sdk-reference/node-js/manage-assets#enable-storage-accounting-for-an-asset). | | `assetType` | `KnowledgeStore` `ItemAssetType` | No | The type of item to create. Values: `video`, `image`. | | `itemMetadata` | `Record` | No | Custom metadata for the item. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 50 key-value pairs. | | `metadata` | `Record` | No | Deprecated. Use `itemMetadata` instead. The item stores the pairs in its `itemMetadata` field and not in its `metadata` field. Send `itemMetadata` or `metadata`, not both. A request that sets both returns a `400` error. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItem` object. The `KnowledgeStoreItem` object contains the following properties: | Name | Type | Description | | :----------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the knowledge store item. | | `assetType` | `KnowledgeStore` `ItemAssetType` | The type of item. Values: `video`, `image`. | | `assetId` | `string` | The unique identifier of the source asset. | | `status` | `KnowledgeStore` `ItemStatus` | The processing status of the item. Values: `queued`, `pending`, `processing`, `ready`, `failed`. For the meaning of each value, see the [Item statuses](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#item-statuses) section on **The knowledge store item object** page. | | `systemMetadata` | `KnowledgeStore` `ItemSystemMetadata` | System-generated metadata for the source asset. Its `assetType` field always matches the item's top-level `assetType` field. | | `metadata` | `Record` | 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 [`updateUserMetadata`](/v1.3/sdk-reference/node-js/manage-assets#update-the-user-defined-metadata-of-an-asset) method of `client.assets`. To set custom metadata for the knowledge store item only, use `itemMetadata`. | | `itemMetadata` | `Record` | 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 `itemMetadata` field. You set it when you create the item or change it with the [`updateKnowledgeStoreItemMetadata`](/v1.3/sdk-reference/node-js/knowledge-store-items#update-the-item-metadata) or [`replaceKnowledgeStoreItemMetadata`](/v1.3/sdk-reference/node-js/knowledge-store-items#replace-the-item-metadata) methods of `client.knowledgeStoreItems`. This field is absent when no item metadata has been set. | | `enrichedMetadata` | `Record` | 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. | | `createdAt` | `string` | The date and time when the item was created, in the RFC 3339 format. | | `updatedAt` | `string` | The date and time when the item was last updated, in the RFC 3339 format. | ### API Reference [Create a knowledge store item](/v1.3/api-reference/knowledge-store-items/create). ### Related guide [Add assets to a knowledge store](/v1.3/agents/guides/add-assets). ## List knowledge store items **Description**: This method returns a list of items in the specified knowledge store. **Function signature and example**: **`Function signature`** ```javascript Function signature list( knowledgeStoreId: string, request?: TwelvelabsApi.KnowledgeStoreItemsListRequest, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const items = await client.knowledgeStoreItems.list("", { // page: 1, // pageLimit: 10, // sortBy: "created_at", // sortOption: "desc", // status: ["ready"], }); for await (const item of items) { console.log(`ID: ${item.id} Type: ${item.assetType} Status: ${item.status}`); } ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :---------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `page` | `number` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `sortBy` | `KnowledgeStore` `ItemsListRequestSortBy` | No | The field to sort on. The following options are available: - `created_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item was created. - `updated_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item was last updated. **Default**: `created_at`. | | `sortOption` | `string` | No | The sorting direction. The following options are available: - `asc` - `desc` **Default**: `desc`. | | `status` | `KnowledgeStore` `ItemsListRequestStatusItem[]` | No | Filter by one or more item processing statuses. Values: `queued`, `pending`, `processing`, `ready`, `failed`. For the meaning of each value, see the [Item statuses](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#item-statuses) section on **The knowledge store item object** page. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `Page` object that allows you to iterate through the paginated list of items. For the properties of each `KnowledgeStoreItem` object, see [Create a knowledge store item](#create-a-knowledge-store-item). ### API Reference [List knowledge store items](/v1.3/api-reference/knowledge-store-items/list). ## Retrieve a knowledge store item **Description**: This method retrieves the details of a specific knowledge store item. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieve( knowledgeStoreId: string, itemId: string, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const item = await client.knowledgeStoreItems.retrieve( "", "", ); console.log(`Type: ${item.assetType} Status: ${item.status}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItem` object. For its properties, see [Create a knowledge store item](#create-a-knowledge-store-item). ### API Reference [Retrieve a knowledge store item](/v1.3/api-reference/knowledge-store-items/retrieve). ## Delete a knowledge store item **Description**: This method deletes the specified knowledge store item. **Function signature and example**: **`Function signature`** ```javascript Function signature delete( knowledgeStoreId: string, itemId: string, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.knowledgeStoreItems.delete( "", "", ); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Delete a knowledge store item](/v1.3/api-reference/knowledge-store-items/delete). ## Update the item metadata **Description**: This method updates the `itemMetadata` of the specified knowledge store item and returns the item. The platform merges your changes with the existing metadata: * A key with a value creates or replaces that key. * A key set to `null` deletes that key. * A key set to an empty string (`""`) or an empty array (`[]`) is ignored. * A key you omit from the request keeps its current value. The `metadata` field of the item does not change. If the merged result contains more than 50 pairs, the request fails. To replace all item metadata in a single call, use the [Replace the item metadata](#replace-the-item-metadata) method instead. **Function signature and example**: **`Function signature`** ```javascript Function signature updateKnowledgeStoreItemMetadata( knowledgeStoreId: string, itemId: string, request: TwelvelabsApi.UpdateKnowledgeStoreItemMetadataRequest, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const item = await client.knowledgeStoreItems.updateKnowledgeStoreItemMetadata( "", "", { itemMetadata: { creator_handle: "@jane.doe", verified: null, }, }, ); console.log(`ID: ${item.id} Status: ${item.status}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `itemMetadata` | `Record` | Yes | The keys to change. Send at least one key. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, an array of strings, or `null` to delete the key. A nested object and an array containing anything other than strings are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItem` object. For its properties, see [Create a knowledge store item](#create-a-knowledge-store-item). ### API Reference [Update the item metadata](/v1.3/api-reference/knowledge-store-items/update-item-metadata). ## Replace the item metadata **Description**: This method replaces the entire `itemMetadata` of the specified knowledge store item and returns the item. Unlike the [Update the item metadata](#update-the-item-metadata) method, which merges your changes with the existing metadata, this method overwrites the stored value in full: * A key with a value creates or replaces that key. * A key you omit, or set to an empty string (`""`), an empty array (`[]`), or `null`, is removed. To clear all item metadata, send an empty object (`{}`) in the `itemMetadata` field. The `metadata` field of the item does not change. **Function signature and example**: **`Function signature`** ```javascript Function signature replaceKnowledgeStoreItemMetadata( knowledgeStoreId: string, itemId: string, request: TwelvelabsApi.ReplaceKnowledgeStoreItemMetadataRequest, requestOptions?: KnowledgeStoreItems.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const item = await client.knowledgeStoreItems.replaceKnowledgeStoreItemMetadata( "", "", { itemMetadata: { creator_handle: "@jane.doe", view_count: 48210, }, }, ); console.log(`ID: ${item.id} Status: ${item.status}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `itemMetadata` | `Record` | Yes | The complete `itemMetadata` of the item after the request. Up to 50 pairs. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, or an array of strings. A nested object and an array containing anything other than strings are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string. | | `requestOptions` | `KnowledgeStoreItems.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItem` object. For its properties, see [Create a knowledge store item](#create-a-knowledge-store-item). ### API Reference [Replace the item metadata](/v1.3/api-reference/knowledge-store-items/replace-item-metadata). # Item tags The `KnowledgeStoreItemTags` class provides methods to tag moments and ranges of video items. A tag carries custom metadata. ## Create an item tag **Description**: This method tags a moment or a range of a video item and returns the tag. Set `startSec` to tag a moment. Set `startSec` and `endSec` to tag a range. A video item holds up to 100 tags. The method returns a `422` error for an item that is not a video item, and when the item already holds 100 tags. **Function signature and example**: **`Function signature`** ```javascript Function signature create( knowledgeStoreId: string, itemId: string, request: TwelvelabsApi.CreateKnowledgeStoreItemTagRequest, requestOptions?: KnowledgeStoreItemTags.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const tag = await client.knowledgeStoreItemTags.create( "", "", { startSec: 12.5, endSec: 18.25, tagMetadata: { event: "goal", team: "home" }, }, ); console.log(`ID: ${tag.id} Start: ${tag.startSec} End: ${tag.endSec}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :---------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `startSec` | `number` | Yes | The start of the tag, in seconds from the start of the video. The value must be 0 or greater. It must be less than the duration of the video. | | `endSec` | `number` | No | The end of the range, in seconds from the start of the video. It must be greater than `startSec`. It must not exceed the duration of the video. Omit it, or send `null`, to tag a single moment. | | `tagMetadata` | `Record` | Yes | The custom metadata of the tag, as key-value pairs. Send at least one key. Up to 50 pairs. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, or an array of strings. A nested object, an array containing anything other than strings, and a null value are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string. | | `requestOptions` | `KnowledgeStoreItem` `Tags.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemTag` object. The `KnowledgeStoreItemTag` object contains the following properties: | Name | Type | Description | | :----------------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the item tag. | | `knowledgeStoreId` | `string` | The unique identifier of the knowledge store. | | `itemId` | `string` | The unique identifier of the knowledge store item that holds the tag. | | `startSec` | `number` | The start of the tag, in seconds from the start of the video. | | `endSec` | `number` | The end of the range, in seconds from the start of the video. The field is absent for a tag on a single moment. | | `tagMetadata` | `Record` | The custom metadata of the tag. Keys are strings. Each value is a string, a number, a boolean, or an array of strings. | | `createdAt` | `string` | The date and time when the tag was created, in the RFC 3339 format. | | `updatedAt` | `string` | The date and time when the tag was last updated, in the RFC 3339 format. | ### API Reference [Create an item tag](/v1.3/api-reference/knowledge-store-items/item-tags/create). ## List item tags **Description**: This method returns the tags of the specified knowledge store item. The platform sorts the tags by `startSec`, earliest first. Tags with the same `startSec` are sorted by `id`. **Function signature and example**: **`Function signature`** ```javascript Function signature list( knowledgeStoreId: string, itemId: string, request?: TwelvelabsApi.KnowledgeStoreItemTagsListRequest, requestOptions?: KnowledgeStoreItemTags.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const tags = await client.knowledgeStoreItemTags.list("", "", { // page: 1, // pageLimit: 10, }); for await (const tag of tags) { console.log(`ID: ${tag.id} Start: ${tag.startSec}`); } ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `page` | `number` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `requestOptions` | `KnowledgeStoreItem` `Tags.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `Page` object that allows you to iterate through the paginated list of item tags. For the properties of each `KnowledgeStoreItemTag` object, see [Create an item tag](#create-an-item-tag). ### API Reference [List item tags](/v1.3/api-reference/knowledge-store-items/item-tags/list). ## Retrieve an item tag **Description**: This method retrieves the details of a specific tag of a knowledge store item. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieve( knowledgeStoreId: string, itemId: string, tagId: string, requestOptions?: KnowledgeStoreItemTags.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const tag = await client.knowledgeStoreItemTags.retrieve( "", "", "", ); console.log(`Start: ${tag.startSec} End: ${tag.endSec}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `tagId` | `string` | Yes | The unique identifier of the item tag. | | `requestOptions` | `KnowledgeStoreItem` `Tags.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemTag` object. For its properties, see [Create an item tag](#create-an-item-tag). ### API Reference [Retrieve an item tag](/v1.3/api-reference/knowledge-store-items/item-tags/retrieve). ## Update an item tag **Description**: This method updates the range or the `tagMetadata` of the specified tag and returns the tag. Send at least one field. A field you omit keeps its current value. To clear the end of the range, send `endSec` as `null`. The tag becomes a single moment. The platform merges your changes to `tagMetadata` with the existing metadata: * A key with a value creates or replaces that key. * A key set to `null` deletes that key. * A key set to an empty string (`""`) or an empty array (`[]`) is ignored. * A key you omit from the request keeps its current value. The tag must keep at least one key in `tagMetadata`, and it holds up to 50 pairs. If the merged result breaks either limit, the request fails. **Function signature and example**: **`Function signature`** ```javascript Function signature update( knowledgeStoreId: string, itemId: string, tagId: string, request?: TwelvelabsApi.UpdateKnowledgeStoreItemTagRequest, requestOptions?: KnowledgeStoreItemTags.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const tag = await client.knowledgeStoreItemTags.update( "", "", "", { endSec: 18.25, tagMetadata: { replay: null }, }, ); console.log(`End: ${tag.endSec}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `tagId` | `string` | Yes | The unique identifier of the item tag. | | `startSec` | `number` | No | The new start of the tag, in seconds from the start of the video. The value must be 0 or greater. It must be less than the duration of the video. The tag must still end after it starts. | | `endSec` | `number` | No | The new end of the range, in seconds from the start of the video. It must be greater than `startSec`. It must not exceed the duration of the video. Send `null` to clear the end, which turns a range into a single moment. Omit the field to keep the current end. | | `tagMetadata` | `Record` | No | The keys to change. Send at least one key. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, an array of strings, or `null` to delete the key. A key you omit keeps its current value. A nested object and an array containing anything other than strings are rejected. The tag holds up to 50 pairs after the merge. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string. | | `requestOptions` | `KnowledgeStoreItem` `Tags.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemTag` object. For its properties, see [Create an item tag](#create-an-item-tag). ### API Reference [Update an item tag](/v1.3/api-reference/knowledge-store-items/item-tags/update). ## Delete an item tag **Description**: This method deletes the specified tag of a knowledge store item. **Function signature and example**: **`Function signature`** ```javascript Function signature delete( knowledgeStoreId: string, itemId: string, tagId: string, requestOptions?: KnowledgeStoreItemTags.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.knowledgeStoreItemTags.delete( "", "", "", ); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `itemId` | `string` | Yes | The unique identifier of the knowledge store item. | | `tagId` | `string` | Yes | The unique identifier of the item tag. | | `requestOptions` | `KnowledgeStoreItem` `Tags.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Delete an item tag](/v1.3/api-reference/knowledge-store-items/item-tags/delete). # Item collections The `KnowledgeStoreItemCollections` class provides methods to organize items into named collections that you can reference together. ## Create an item collection **Description**: This method creates an item collection in the specified knowledge store. An item collection is a named collection of items. Use item collections to organize and reference subsets of items together. **Function signature and example**: **`Function signature`** ```javascript Function signature create( knowledgeStoreId: string, request: TwelvelabsApi.KnowledgeStoreItemCollectionsCreateRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const collection = await client.knowledgeStoreItemCollections.create("", { name: "Q1 highlights", // description: "A subset of items", // metadata: { group: "highlights" }, }); console.log(`ID: ${collection.id} Name: ${collection.name}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `name` | `string` | Yes | The name of the item collection. Must be unique within the knowledge store. | | `description` | `string` | No | An optional description of the item collection. | | `metadata` | `Record` | No | Custom metadata for the item collection. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 10 key-value pairs. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemCollection` object. The `KnowledgeStoreItemCollection` object contains the following properties: | Name | Type | Description | | :----------------- | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier of the item collection. | | `knowledgeStoreId` | `string` | The unique identifier of the knowledge store this collection belongs to. | | `name` | `string` | The name of the item collection. | | `description` | `string` | The description of the item collection. | | `metadata` | `Record` | Custom metadata for the item collection. Keys are strings; each value is a string, a number, a boolean, or an array of strings. | | `memberCount` | `number` | The number of items in the collection. | | `createdAt` | `string` | The date and time when the item collection was created, in the RFC 3339 format. | | `updatedAt` | `string` | The date and time when the item collection was last updated, in the RFC 3339 format. | ### API Reference [Create an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/create). ## List item collections **Description**: This method returns a list of the item collections in the specified knowledge store. **Function signature and example**: **`Function signature`** ```javascript Function signature list( knowledgeStoreId: string, request?: TwelvelabsApi.KnowledgeStoreItemCollectionsListRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const collections = await client.knowledgeStoreItemCollections.list("", { // page: 1, // pageLimit: 10, // sortBy: "created_at", // sortOption: "desc", }); for await (const collection of collections) { console.log(`ID: ${collection.id} Name: ${collection.name}`); } ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :----------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `page` | `number` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `sortBy` | `KnowledgeStoreItem` `CollectionsList` `RequestSortBy` | No | The field to sort on. The following options are available: - `created_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item collection was created. - `updated_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item collection was last updated. - `name`: Sorts alphabetically by the name of the item collection. **Default**: `created_at`. | | `sortOption` | `string` | No | The sorting direction. The following options are available: - `asc` - `desc` **Default**: `desc`. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `Page` object that allows you to iterate through the paginated list of item collections. For the properties of each `KnowledgeStoreItemCollection` object, see [Create an item collection](#create-an-item-collection). ### API Reference [List item collections](/v1.3/api-reference/knowledge-store-items/item-collections/list). ## Retrieve an item collection **Description**: This method retrieves the details of a specific item collection. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieve( knowledgeStoreId: string, collectionId: string, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const collection = await client.knowledgeStoreItemCollections.retrieve( "", "", ); console.log(`Name: ${collection.name} Members: ${collection.memberCount}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemCollection` object. For its properties, see [Create an item collection](#create-an-item-collection). ### API Reference [Retrieve an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/retrieve). ## Update an item collection **Description**: This method updates the `name`, `description`, and `metadata` fields of the specified item collection. **Function signature and example**: **`Function signature`** ```javascript Function signature update( knowledgeStoreId: string, collectionId: string, request?: TwelvelabsApi.KnowledgeStoreItemCollectionsUpdateRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const collection = await client.knowledgeStoreItemCollections.update( "", "", { // name: "Updated name", // description: "Updated collection description", // metadata: { group: "highlights" }, }, ); console.log(`Description: ${collection.description}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `name` | `string` | No | The name of the item collection. Must be unique within the knowledge store. | | `description` | `string` | No | An optional description of the item collection. | | `metadata` | `Record` | No | Custom metadata for the item collection. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 10 key-value pairs. The provided object replaces the existing metadata in full, so include every key you want to keep and omit the ones you want to remove. To clear all metadata, set this field to an empty object (`{}`). | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemCollection` object. For its properties, see [Create an item collection](#create-an-item-collection). ### API Reference [Update an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/update). ## Delete an item collection **Description**: This method deletes the specified item collection. The items themselves remain in the knowledge store. **Function signature and example**: **`Function signature`** ```javascript Function signature delete( knowledgeStoreId: string, collectionId: string, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.knowledgeStoreItemCollections.delete( "", "", ); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Delete an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/delete). ## List items in an item collection **Description**: This method returns a list of the items in the specified item collection. **Function signature and example**: **`Function signature`** ```javascript Function signature listItems( knowledgeStoreId: string, collectionId: string, request?: TwelvelabsApi.KnowledgeStoreItemCollectionsListItemsRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const items = await client.knowledgeStoreItemCollections.listItems( "", "", { // page: 1, // pageLimit: 10, }, ); for await (const item of items) { console.log(`ID: ${item.id} Type: ${item.assetType}`); } ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `page` | `number` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `Page` object that allows you to iterate through the paginated list of items in the collection. For the properties of each `KnowledgeStoreItem` object, see [Create a knowledge store item](#create-a-knowledge-store-item). ### API Reference [List items in an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/list-items). ## Add items to an item collection **Description**: This method adds one or more items to the specified item collection. This operation is idempotent — items already in the collection are skipped. Every identifier must reference an existing item in the knowledge store. **Function signature and example**: **`Function signature`** ```javascript Function signature addItems( knowledgeStoreId: string, collectionId: string, request: TwelvelabsApi.KnowledgeStoreItemCollectionsAddItemsRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const collection = await client.knowledgeStoreItemCollections.addItems( "", "", { itemIds: [""] }, ); console.log(`Members: ${collection.memberCount}`); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `itemIds` | `string[]` | Yes | The unique identifiers of the items to add to the collection. Include up to 500 identifiers per request. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `KnowledgeStoreItemCollection` object. For its properties, see [Create an item collection](#create-an-item-collection). ### API Reference [Add items to an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/add-items). ## Remove items from an item collection **Description**: This method removes one or more items from the specified item collection. This operation is idempotent — identifiers that do not match a member of the collection are ignored. The items themselves remain in the knowledge store. **Function signature and example**: **`Function signature`** ```javascript Function signature removeItems( knowledgeStoreId: string, collectionId: string, request: TwelvelabsApi.KnowledgeStoreItemCollectionsRemoveItemsRequest, requestOptions?: KnowledgeStoreItemCollections.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.knowledgeStoreItemCollections.removeItems( "", "", { itemIds: [""] }, ); ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :--------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `collectionId` | `string` | Yes | The unique identifier of the knowledge store item collection. | | `itemIds` | `string[]` | Yes | The unique identifiers of the items to remove from the collection. Include up to 500 identifiers per request. | | `requestOptions` | `KnowledgeStoreItem` `Collections.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Remove items from an item collection](/v1.3/api-reference/knowledge-store-items/item-collections/remove-items).