> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://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://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. # Manage entities > Manage entities and entity collections. > **Info** > > The Entity Search feature is currently in beta. The SDK offers methods for managing entities related to video search. It operates with three types of resources: * **Assets**: Reference images of the persons you wish to identify. * **Entity collections**: Logical groupings of related entities, such as players on a team. * **Entities**: Specific persons you want to locate in videos, associated with their reference images. > **Note** > > * To use the Entity Search feature, the Marengo video understanding model must be enabled in your index. > * The platform automatically creates a sample entity collection when you create your account. Users on the Free plan can have a total of one entity collection with up to fifteen entities. The default collection is included in this limit. To create more entity collections, upgrade to the Developer plan. For instructions, see the [Upgrade your plan](/v1.3/docs/get-started/manage-your-plan#upgrade-your-plan) section. # Assets Assets are reference images that help identify people in videos. Upload multiple images per person to improve identification accuracy. For a complete reference on how to create assets, see the [Direct uploads](/v1.3/sdk-reference/node-js/upload-content/direct-uploads) section. # Entity collections Entity collections organize related entities into logical groups. ## List entity collections **Description**: This method returns a list of the entity collections in your account. **Function signature and example**: **`Function signature`** ```typescript Function signature list(request?: TwelvelabsApi.EntityCollectionsListRequest, requestOptions?: EntityCollections.RequestOptions): Promise> ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const collectionsPager = await client.entityCollections.list( // { // page: 1, // pageLimit: 10, // name: "", // sortOption: "desc", // } ); for await (const collection of collectionsPager) { console.log(`\nEntity collection ID: ${collection.id}`); console.log(`Name: ${collection.name}`); console.log(`Description: ${collection.description}`); console.log(`Created at: ${collection.createdAt}`); console.log(`Updated at: ${collection.updatedAt}`); console.log("-".repeat(50)); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :------------------------------------------- | :------- | :----------------------------------------------------------------------- | | `request` | `TwelvelabsApi.EntityCollectionsListRequest` | No | Parameters for retrieving the list of entity collections. Default: `{}`. | | `requestOptions` | `EntityCollections.RequestOptions` | No | Request-specific configuration | The `EntityCollectionsListRequest` interface defines the parameters for listing entity collections: | Name | Type | Required | Description | | :--------------- | :------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | | `name` | `string` | No | Filter entity collections by name. | | `sortBy` | `TwelvelabsApi.EntityCollectionsListRequestSortBy` | 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 entity collection was updated. - `updated_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the entity collection was created. - `name`: Sorts by the name. | | `sortOption` | `string` | No | The sorting direction. The following options are available: `asc` and `desc`. Default: `desc`. | | `requestOptions` | `Assets.RequestOptions` | No | Request-specific configuration | ### Return value Returns a `Promise` that resolves to a `core.Page` instance, representing the entity collections that match the specified criteria. The `Page` class contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `getNextPage()` | `Promise` | Retrieves the next page and returns the updated `Page` object. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `EntityCollection` interface contains the following properties: | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier for the entity collection. | | `name` | `string` | The name of the entity collection. | | `description` | `string` | The description of the entity collection. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was created. | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was last updated. | ### API Reference [List entity collections](/v1.3/api-reference/entities/entity-collections/list) ## Create an entity collection Description\*\*: This method creates an entity collection. > **Note** > > Free plan users can create one entity collection with up to 15 entities. If your needs exceed the Free plan, consider [upgrading to the Developer plan](/v1.3/docs/get-started/manage-your-plan#upgrade-your-plan). **Function signature and example**: **`Function signature`** ```typescript Function signature create(request: TwelvelabsApi.EntityCollectionsCreateRequest, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.entityCollections.create({ name: "", description: "", }); console.log(`Entity collection ID: ${response.id}`); console.log(`Name: ${response.name}`); console.log(`Description: ${response.description}`); console.log(`Created at: ${response.createdAt}`); console.log(`Updated at: ${response.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :--------------------------------------------- | :------- | :--------------------------------------------- | | `request` | `TwelvelabsApi.EntityCollectionsCreateRequest` | Yes | Parameters for creating the entity collection. | | `requestOptions` | `EntityCollections.RequestOptions` | No | Request-specific configuration | The `EntityCollectionsCreateRequest` interface defines the parameters for creating an entity collection: | Name | Type | Required | Description | | :------------ | :------- | :------- | :------------------------------------------------------------------------------------ | | `name` | `string` | Yes | The name of the entity collection. Make sure you use a succinct and descriptive name. | | `description` | `string` | No | A description of the entity collection. | ### Return value Returns an `HttpResponsePromise` that resolves to an `EntityCollection` object representing the newly created entity collection. The `EntityCollection` interface contains the following properties: | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier for the entity collection. | | `name` | `string` | The name of the entity collection. | | `description` | `string` | The description of the entity collection. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was created. | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was last updated. | ### API Reference [Create an entity collection](/v1.3/api-reference/entities/entity-collections/create) ## Retrieve an entity collection **Description**: This method retrieves details about the specified entity collection. **Function signature and example**: **`Function signature`** ```typescript Function signature retrieve(entityCollectionId: string, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; response = await client.entityCollections.retrieve(""); console.log(`Entity collection ID: ${response.id}`); console.log(`Name: ${response.name}`); console.log(`Description: ${response.description}`); console.log(`Created at: ${response.createdAt}`); console.log(`Updated at: ${response.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :--------------------------------- | :------- | :---------------------------------------------------------- | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection to retrieve. | | `requestOptions` | `EntityCollections.RequestOptions` | No | Request-specific configuration | ### Return value Returns an `HttpResponsePromise` that resolves to an `EntityCollection` object representing the specified entity collection. The `EntityCollection` interface contains the following properties: | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier for the entity collection. | | `name` | `string` | The name of the entity collection. | | `description` | `string` | The description of the entity collection. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was created. | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was last updated. | ### API Reference [Retrieve an entity collection](/v1.3/api-reference/entities/entity-collections/retrieve) ## Update an entity collection **Description**: This method updates the specified entity collection. **Function signature and example**: **`Function signature`** ```typescript Function signature update(entityCollectionId: string, request?: TwelvelabsApi.EntityCollectionsUpdateRequest, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise; ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.entityCollections.update("", { name: "", description: "", }); console.log(`Entity collection ID: ${response.id}`); console.log(`Name: ${response.name}`); console.log(`Description: ${response.description}`); console.log(`Created at: ${response.createdAt}`); console.log(`Updated at: ${response.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :--------------------------------------------- | :------- | :------------------------------------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection to update. | | `request` | `TwelvelabsApi.EntityCollectionsUpdateRequest` | No | Parameters for updating the entity collection. Default: `{}`. | | `requestOptions` | `EntityCollections.RequestOptions` | No | Request-specific configuration | The `EntityCollectionsUpdateRequest` interface defines the parameters for updating an entity collection: | Name | Type | Required | Description | | :------------ | :------- | :------- | :------------------------------------------------ | | `name` | `string` | No | The updated name of the entity collection. | | `description` | `string` | No | The updated description of the entity collection. | ### Return value Returns an `HttpResponsePromise` that resolves to an `EntityCollection` object representing the updated entity collection. The `EntityCollection` interface contains the following properties: | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier for the entity collection. | | `name` | `string` | The name of the entity collection. | | `description` | `string` | The description of the entity collection. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was created. | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity collection was last updated. | ### API Reference [Update an entity collection](/v1.3/api-reference/entities/entity-collections/update) ## Delete an entity collection **Description**: This method deletes the specified entity collection. This action cannot be undone. **Function signature and example**: **`Function signature`** ```typescript Function signature delete(entityCollectionId: string, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise; ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.entityCollections.delete(""); ``` ### Parameters | Name | Type | Required | Description | | | :------------------- | :--------------------------------- | :------- | :-------------------------------------------------------- | ------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection to delete. | | | `requestOptions` | `EntityCollections.RequestOptions` | No | | Request-specific configuration | ### Return value Returns an `HttpResponsePromise` that resolves when the entity collection has been successfully deleted. ### API Reference [Delete an entity collection](/v1.3/api-reference/entities/entity-collections/delete) # Entities Entities represent logical groupings of related entities. ## List entities by asset **Description**: This method returns a list of entities whose `assetIds` array contains the specified asset. **Function signature and example**: **`Function signature`** ```typescript Function signature listByAsset(assetId: string, request?: TwelvelabsApi.entityCollections.EntitiesListByAssetRequest, requestOptions?: Entities.RequestOptions): Promise> ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.entityCollections.entities.listByAsset( "", { page: 1, pageLimit: 10, } ); for await (const entity of response) { console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Status: ${entity.status}`); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :----------------------------------------------------------- | :------- | :---------------------------------------- | | `assetId` | `string` | Yes | The unique identifier of the asset. | | `request` | `TwelvelabsApi.entityCollections.EntitiesListByAssetRequest` | No | Parameters for listing entities by asset. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | The `EntitiesListByAssetRequest` interface has the following properties: | Name | Type | Required | Description | | :---------- | :------- | :------- | :-------------------------------------------------------------------- | | `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`. | ### Return value Returns a `Promise` that resolves to a `core.Page` instance, representing the entities that reference the specified asset. The `Page` class contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `getNextPage()` | `Promise` | Retrieves the next page and returns the updated `Page` object. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | | ### API Reference [List entities for an asset](/v1.3/api-reference/entities/list-entities-by-asset) ## List entities in an entity collection **Description**: This method returns a list of the entities in the specified entity collection. **Function signature and example**: **`Function signature`** ```typescript Function signature list(entityCollectionId: string, request?: TwelvelabsApi.entityCollections.EntitiesListRequest, requestOptions?: Entities.RequestOptions): Promise> ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const entitiesPager = await client.entityCollections.entities.list( "", // { // page: 1, // pageLimit: 10, // name: "", // sortOption: "desc", // } ); for await (const entity of entitiesPager) { console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Description: ${entity.description}`); console.log(`Metadata: ${entity.metadata}`); console.log(`Asset IDs: ${entity.assetIds}`); console.log(`Status: ${entity.status}`); console.log(`Created at: ${entity.createdAt}`); console.log(`Updated at: ${entity.updatedAt}`); console.log("-".repeat(50)); } ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :---------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection for which the platform will retrieve the entities. | | `request` | `TwelvelabsApi.entityCollections.EntitiesListRequest` | No | Parameters for retrieving the list of entities. Default: `{}`. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | The `EntitiesListRequest` interface defines the parameters for listing entities in an entity collection: | Name | Type | Required | Description | | | :------------ | :---------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | | `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. | | | `name` | `string` | | No | Filter entities by name. | | `status` | `TwelvelabsApi.entityCollections.EntitiesListRequestStatus` | No | Filter entities by status. Values: `processing`, `ready`. | | | `sortBy` | `TwelvelabsApi.entityCollections.EntitiesListRequestSortBy` | 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 entity was created. - `updated_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the entity was updated. - `name`: Sorts by the name. | | | `sort_option` | `typing.Optional[str]` | No | The sorting direction. The following options are available: `asc` and `desc`. Default: `desc`. | | | `sortOption` | `string` | No | | | ### Return value Returns a `Promise` that resolves to a `core.Page` instance, representing the entities that match the specified criteria. The `Page` class contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `getNextPage()` | `Promise` | Retrieves the next page and returns the updated `Page` object. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | | ### API Reference [List entities in an entity collection](/v1.3/api-reference/entities/entity-collections/entities/list) ## Create an entity **Description**: This method creates an entity within a specified entity collection. Each entity must be associated with at least one asset. **Function signature and example**: **`Function signature`** ```typescript Function signature create(entityCollectionId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise; ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const entity = await client.entityCollections.entities.create( "", { name: "", assetIds: ["", ""], } ); console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Description: ${entity.description}`); console.log(`Metadata: ${entity.metadata}`); console.log(`Asset IDs: ${entity.assetIds}`); console.log(`Status: ${entity.status}`); console.log(`Created at: ${entity.createdAt}`); console.log(`Updated at: ${entity.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :------------------------------------------------------ | :------- | :---------------------------------------------------------------------------- | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection in which to create the entity. | | `request` | `TwelvelabsApi.entityCollections.EntitiesCreateRequest` | Yes | Parameters for creating the entity. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | The `EntitiesCreateRequest` interface defines the parameters for creating an entity: | Name | Type | Required | Description | | | :------------ | :------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `name` | `string` | Yes | The name of the entity. Make sure you use a succinct and descriptive name. | | | `description` | `string` | No | An optional description of the entity. | | | `assetIds` | `string[]` | Yes | | An array of asset IDs to associate with the entity. You must provide at least one value. | | `metadata` | `Record` | No | Optional metadata for the entity, provided as key-value pairs to store additional context or attributes. Use metadata to categorize or describe the entity for easier management and search. Keys must be of type `string`, and values can be of type `string`, `integer`, `float`, or `boolean`. | | ### Return value Returns an `HttpResponsePromise` that resolves to an `Entity` object representing the newly created entity. The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | . | ### API Reference [Create an entity](/v1.3/api-reference/entities/entity-collections/entities/create) ## Create multiple entities in bulk **Description**: This method creates multiple entities within a specified entity collection in a single request. Each entity must be associated with at least one asset. This method is useful for efficiently adding multiple entities, such as a roster of players or a group of characters. **Function signature and example**: **`Function signature`** ```typescript Function signature createBulk(entityCollectionId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateBulkRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.entityCollections.entities.createBulk( "", { entities: [ { name: "", assetIds: ["", ""], }, { name: "", assetIds: ["", ""], } ], } ); console.log(`Success Count: ${response.successCount}`); console.log(`Failed Count: ${response.failedCount}`); if (response.entities) { for (const entity of response.entities) { console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Status: ${entity.status}`); console.log("-".repeat(50)); } } if (response.errors) { for (const error of response.errors) { console.log(`\nError entity index: ${error.entityIndex}`); console.log(`Error entity name: ${error.entityName}`); console.log(`Error reason: ${error.errorReason}`); console.log("-".repeat(50)); } } ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :---------------------------------------------------------- | :------- | :------------------------------------------------------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection in which to create the entities. | | `request` | `TwelvelabsApi.entityCollections.EntitiesCreateBulkRequest` | Yes | Parameters for creating multiple entities in bulk. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | The `EntitiesCreateBulkRequest` interface defines the parameters for creating multiple entities in bulk. It's an array of `TwelvelabsApi.entityCollections.EntitiesCreateBulkRequestEntitiesItem` objects, each representing an entity to be created. The `EntitiesCreateBulkRequestEntitiesItem` interface defines the parameters for each entity to be created: | Name | Type | Required | Description | | | :------------ | :--------- | :------------------------ | :--------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Yes | The name of the entity. Make sure you use a succinct and descriptive name. | | | `description` | `string` | No | An optional description of the entity. | | | `assetIds` | `string[]` | Yes | An array of asset IDs to associate with the entity. You must provide at least one value. | | | `metadata` | | `Record` | No | Optional metadata for the entity, provided as key-value pairs to store additional context or attributes. Use metadata to categorize or describe the entity for easier management and search. Keys must be of type `string`, and values can be of type `string`, `integer`, `float`, or `boolean`. | ### Return value Returns an `HttpResponsePromise` that resolves to a `BulkCreateEntityResponse` object. The `BulkCreateEntityResponse` interface contains the following properties: | Name | Type | Description | | :------------- | :----------------------------------------------------- | :-------------------------------------------------------------------------------------- | | `successCount` | `number` | The number of entities that were successfully created. | | `failedCount` | `number` | The number of entities that failed to be created due to errors, such as missing assets. | | `entities` | `TwelvelabsApi.BulkCreateEntityResponseEntitiesItem[]` | An array of objects representing the entities that were successfully created. | | `errors` | `TwelvelabsApi.BulkCreateEntityResponseErrorsItem[]` | An array of error objects for entities that failed to be created. | The `BulkCreateEntityResponseEntitiesItem` interface contains the following properties: | Name | Type | Description | | :------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the created entity. | | `name` | `string` | The name of the created entity. | | `status` | `string` | The status of the entity. Values: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | The `BulkCreateEntityResponseErrorsItem` interface contains the following properties: | Name | Type | Description | | :------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------- | | `entityIndex` | `number` | The zero-based index of the entity in the original request array. This helps identify which specific entity failed to be created. | | `entityName` | `string` | The name of the entity that failed to be created, as provided in the request. | | `errorReason` | `string` | A message explaining why the entity failed to be created. | ### API Reference [Create multiple entities in bulk](/v1.3/api-reference/entities/entity-collections/entities/create-bulk) ## Retrieve an entity **Description**: This method retrieves details about the specified entity. **Function signature and example**: **`Function signature`** ```typescript Function signature retrieve(entityCollectionId: string, entityId: string, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const entity = await client.entityCollections.entities.retrieve( "", "" ); console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Description: ${entity.description}`); console.log(`Metadata: ${entity.metadata}`); console.log(`Asset IDs: ${entity.assetIds}`); console.log(`Status: ${entity.status}`); console.log(`Created at: ${entity.createdAt}`); console.log(`Updated at: ${entity.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :------------------------ | :------- | :----------------------------------------------------------------------------------- | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection that contains the entity to retrieve. | | `entityId` | `string` | Yes | The unique identifier of the entity to retrieve. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | ### Return value Returns an `HttpResponsePromise` that resolves to an `Entity` object representing the specified entity. The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | . | ### API Reference [Retrieve an entity](/v1.3/api-reference/entities/entity-collections/entities/retrieve) ## Update an entity **Description**: This method updates the specified entity within an entity collection. This operation allows modification of the entity's name, description, or metadata. Note that this method does not affect the assets associated with the entity. **Function signature and example**: **`Function signature`** ```typescript Function signature update(entityCollectionId: string, entityId: string, request?: TwelvelabsApi.entityCollections.EntitiesUpdateRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const entity = await client.entityCollections.entities.update( "", "", { name: "", description: "", metadata: { "": "" }, } ); console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Description: ${entity.description}`); console.log(`Metadata: ${entity.metadata}`); console.log(`Asset IDs: ${entity.assetIds}`); console.log(`Status: ${entity.status}`); console.log(`Created at: ${entity.createdAt}`); console.log(`Updated at: ${entity.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :------------------------------------------------------ | :------- | :---------------------------------------------------------------------------------- | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection containing the entity to be updated. | | `entityId` | `string` | Yes | The unique identifier of the entity to be updated. | | `request` | `TwelvelabsApi.entityCollections.EntitiesUpdateRequest` | No | Parameters for updating the entity. Default: `{}`. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | The `EntitiesUpdateRequest` interface defines the parameters for updating an entity: | Name | Type | Required | Description | | :------------ | :------------------------ | :------- | :-------------------------------------------------------------------------------------------- | | `name` | `string` | No | The updated name of the entity. | | `description` | `string` | No | The updated description of the entity. | | `metadata` | `Record` | No | Updated metadata for the entity. If provided, this completely replaces the existing metadata. | ### Return value Returns an `HttpResponsePromise` that resolves to an `Entity` object representing the updated entity. The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | . | ### API Reference [Update an entity](/v1.3/api-reference/entities/entity-collections/entities/update) ## Delete an entity **Description**: This method deletes a specific entity from an entity collection. It permanently removes the entity and its associated data, but does not affect the assets associated with this entity. **Function signature and example**: **`Function signature`** ```typescript Function signature delete(entityCollectionId: string, entityId: string, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.entityCollections.entities.delete("", ""); ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :------------------------ | :------- | :---------------------------------------------------------------------------------- | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection containing the entity to be deleted. | | `entityId` | `string` | Yes | The unique identifier of the entity to be deleted. | | `requestOptions` | `Entities.RequestOptions` | No | Request-specific configuration | ### Return value Returns an `HttpResponsePromise` that resolves when the entity has been successfully deleted. ### PI Reference [Delete an entity](/v1.3/api-reference/entities/entity-collections/entities/delete) ## Add assets to an entity **Description**: This method adds assets to the specified entity within an entity collection. Assets are used to identify the entity in media content, and adding multiple assets can improve the accuracy of entity recognition in searches. When assets are added, the entity may temporarily enter the "processing" state while the platform updates the necessary data. Once processing is complete, the entity status will return to "ready." **Function signature and example**: **`Function signature`** ```typescript Function signature createAssets(entityCollectionId: string, entityId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateAssetsRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; const entity = await client.entityCollections.entities.createAssets( "", "", { assetIds: ["", ""], } ); console.log(`\nEntity ID: ${entity.id}`); console.log(`Name: ${entity.name}`); console.log(`Description: ${entity.description}`); console.log(`Metadata: ${entity.metadata}`); console.log(`Asset IDs: ${entity.assetIds}`); console.log(`Status: ${entity.status}`); console.log(`Created at: ${entity.createdAt}`); console.log(`Updated at: ${entity.updatedAt}`); ``` ### Parameters | Name | Type | Required | Description | | | :------------------- | :------------------------------------------------------------ | :------- | :-------------------------------------------------------------------------------------------------- | ------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection containing the entity to which assets will be added. | | | `entityId` | `string` | Yes | The unique identifier of the entity to which assets will be added. | | | `request` | `TwelvelabsApi.entityCollections.EntitiesCreateAssetsRequest` | Yes | Parameters for adding assets to the entity. | | | `requestOptions` | `Entities.RequestOptions` | | No | Request-specific configuration | The `EntitiesCreateAssetsRequest` interface contains an array of strings representing the asset IDs to be added to the entity. ### Return value Returns an `HttpResponsePromise` that resolves to an `Entity` object representing the updated entity with the newly added assets. The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | . | ### API Reference [Add assets to an entity](/v1.3/api-reference/entities/entity-collections/entities/add-assets) ## Remove assets from an entity **Description**: This method removes from the specified entity. Assets are used to identify the entity in media content, and removing assets may impact the accuracy of entity recognition in searches if too few assets remain. When assets are removed, the entity may temporarily enter a "processing" state while the system updates the necessary data. Once processing is complete, the entity status will return to "ready." > **Notes** > > * This operation only removes the association between the entity and the specified assets; it does not delete the assets themselves. > * An entity must always have at least one asset associated with it. You can't remove the last asset from an entity. **Function signature and example**: **`Function signature`** ```typescript Function signature deleteAssets(entityCollectionId: string, entityId: string, request: TwelvelabsApi.entityCollections.EntitiesDeleteAssetsRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise ``` **`Node.js example`** ```typescript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.entityCollections.entities.deleteAssets("", "", { assetIds: [""], }); ``` ### Parameters | Name | Type | Required | Description | | | :------------------- | :------------------------------------------------------------ | :------- | :------------------------------------------------------------------------------------------------------ | ------------------------------ | | `entityCollectionId` | `string` | Yes | The unique identifier of the entity collection containing the entity from which assets will be removed. | | | `entityId` | `string` | Yes | The unique identifier of the entity from which assets will be removed. | | | `request` | `TwelvelabsApi.entityCollections.EntitiesDeleteAssetsRequest` | Yes | Parameters for removing assets from the entity. | | | `requestOptions` | `Entities.RequestOptions` | | No | Request-specific configuration | The `EntitiesDeleteAssetsRequest` interface contains an array of strings representing the asset IDs to be removed from the entity. ### Return value Returns an `HttpResponsePromise` that resolves to an `Entity` object representing the updated entity with the specified assets removed. The `Entity` interface contains the following properties: | Name | Type | Description | | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the entity. | | | `entityCollectionId` | `string` | The unique identifier of the entity collection this entity belongs to. | | | `name` | `string` | The name of the entity. | | | `description` | `string` | A description of the entity. | | | `metadata` | `Record` | Custom metadata for the entity. | | | `assetIds` | `string[]` | An array of asset IDs associated with the entity. | | | `status` | `TwelvelabsApi.EntityStatus` | The status of the entity. Values: `processing`, `ready`. | The current status of the entity creation process. Possible values are: - `processing`: The entity is being processed and is not yet ready for use in searches. - `ready`: The entity is fully processed and can be used in search queries. | | `createdAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created. | | | `updatedAt` | `Date` | The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated. | . | ### API Reference [Remove assets from an entity](/v1.3/api-reference/entities/entity-collections/entities/remove-assets)