The Entity Search feature is currently in beta.

The TwelveLabs Python 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 3.0 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 section.

Assets

Assets are reference images that help identify people in videos. Upload multiple images per person to improve identification accuracy.

List assets

Description: This method returns a list of assets in your account. The platform returns your assets sorted by creation date, with the newest at the top of the list.

Function signature and example:

1 list(request?: TwelvelabsApi.AssetsListRequest, requestOptions?: Assets.RequestOptions): Promise<core.Page<TwelvelabsApi.Asset>>

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.AssetsListRequest`	No	Parameters for retrieving the list of indexes. Default: `{}`.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration

The AssetsListRequest interface defines the parameters for listing assets:

Name	Type	Required	Description
`page`	`number`	No	A number that identifies the page to retrieve. Default: 1.
`page_limit`	`number`	No	The number of items to return on each page. Default: 10. Max: 50.
`asset_ids`	`string \| string[]`	No	A list of asset IDs to filter the results.

Return value: Returns a Promise that resolves to a core.Page<TwelvelabsApi.Asset> instance, representing the assets 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<this>`	Retrieves the next page and returns the updated `Page` object.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	Allows iteration through all items across all pages using `for await` loops.

The Asset class contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier for the asset.
`method`	`TwelvelabsApi.AssetMethod`	The method used to create the asset. Values: `direct`, `url`.
`status`	`TwelvelabsApi.AssetStatus`	The status of the upload process. Values: `waiting`, `processing`, `ready`.
`filename`	`string`	The name of the file used to create the asset.
`fileType`	`string`	The MIME type of the asset file.
`urlExpiresAt`	`Date`	The URL where the asset can be accessed.
`url_expires_at`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the URL expires.
`createdAt`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.

API Reference: List assets

Create an asset

Description: This method creates an asset by uploading an image file or providing a publicly accessible URL.

Note the following about creating assets:

The platform will automatically delete assets not associated with any entity 72 hours after creation.
You can associate a single asset with multiple entities.

Your image files must meet the format requirements.

Ensure URLs point directly to the raw image file without requiring user interaction.

Upload options:

Local file: Set the method parameter to direct and use the file parameter to specify the image file.
Publicly accessible URL: Set the method parameter to url and use the url parameter to specify the URL of your image file.

Function signature and example:

1 create(request: TwelvelabsApi.AssetsCreateRequest, requestOptions?: Assets.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Asset>;

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.AssetsCreateRequest`	Yes	Parameters for creating the asset.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration

The AssetsCreateRequest interface defines the parameters for creating an asset:

Name	Type	Required	Description
`method`	`TwelvelabsApi.AssetsCreateRequestMethod`	Yes	Specifies the upload method for the asset. Use `direct` to upload a local image file or `url` for a publicly accessible URL.
`file`	`File \| fs.ReadStream \| Blob \| undefined`	Conditionally required	Specify this parameter to upload a file from your local file system. This parameter is required when `method` is set to `file`.
`url`	`string`	Conditionally required	Specify this parameter to upload a file using a publicly accessible URL. This parameter is required when `method` is set to `url`.

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.Asset> that resolves to an Asset object representing the newly created asset. The Asset class contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier for the asset.
`method`	`TwelvelabsApi.AssetMethod`	The method used to create the asset. Values: `direct`, `url`.
`status`	`TwelvelabsApi.AssetStatus`	The status of the upload process. Values: `waiting`, `processing`, `ready`.
`filename`	`string`	The name of the file used to create the asset.
`fileType`	`string`	The MIME type of the asset file.
`urlExpiresAt`	`Date`	The URL where the asset can be accessed.
`url_expires_at`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the URL expires.
`createdAt`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.

API Reference: Create an asset

Retrieve an asset

Description: This method retrieves details about the specified asset.

Function signature and example:

1 retrieve(assetId: string, requestOptions?: Assets.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Asset>

Parameters:

Name	Type	Required	Description
`assetId`	`string`	Yes	The unique identifier of the asset to retrieve.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.Asset> that resolves to an Asset object representing the specified asset. The Asset class contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier for the asset.
`method`	`TwelvelabsApi.AssetMethod`	The method used to create the asset. Values: `direct`, `url`.
`status`	`TwelvelabsApi.AssetStatus`	The status of the upload process. Values: `waiting`, `processing`, `ready`.
`filename`	`string`	The name of the file used to create the asset.
`fileType`	`string`	The MIME type of the asset file.
`urlExpiresAt`	`Date`	The URL where the asset can be accessed.
`url_expires_at`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the URL expires.
`createdAt`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.

API Reference: Retrieve an asset

Delete an asset

Description: This method deletes the specified asset. This action cannot be undone.

Function signature and example:

1 delete(assetId: string, requestOptions?: Assets.RequestOptions): core.HttpResponsePromise<void>

Parameters:

Name	Type	Required	Description
`assetId`	`string`	Yes	The unique identifier of the asset to delete.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration

Return value: Returns a core.HttpResponsePromise<void> that resolves when the asset has been successfully deleted.

API Reference: Delete an asset

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:

1 list(request?: TwelvelabsApi.EntityCollectionsListRequest, requestOptions?: EntityCollections.RequestOptions): Promise<core.Page<TwelvelabsApi.EntityCollection>>

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<TwelvelabsApi.EntityCollection> 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<this>`	Retrieves the next page and returns the updated `Page` object.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	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

Create an entity collection

Description: This method creates an entity collection.

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.

Function signature and example:

1 create(request: TwelvelabsApi.EntityCollectionsCreateRequest, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.EntityCollection>

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 a core.HttpResponsePromise<TwelvelabsApi.EntityCollection> 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

Retrieve an entity collection

Description: This method retrieves details about the specified entity collection.

Function signature and example:

1 retrieve(entityCollectionId: string, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.EntityCollection>

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 a core.HttpResponsePromise<TwelvelabsApi.EntityCollection> 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

Update an entity collection

Description: This method updates the specified entity collection.

Function signature and example:

1 update(entityCollectionId: string, request?: TwelvelabsApi.EntityCollectionsUpdateRequest, requestOptions?: EntityCollections.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.EntityCollection>;

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 a core.HttpResponsePromise<TwelvelabsApi.EntityCollection> 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

Delete an entity collection

Description: This method deletes the specified entity collection. This action cannot be undone.

Function signature and example:

Parameters:

Name	Type	Required	Description
`entityCollectionId`	`string`	Yes	The unique identifier of the entity collection to delete.
`requestOptions`	`EntityCollections.RequestOptions`	No

Return value: Returns a core.HttpResponsePromise<void> that resolves when the entity collection has been successfully deleted.

API Reference: Delete an entity collection

Entities

Entities represent logical groupings of related entities.

List entities in an entity collection

Description: This method returns a list of the entities in the specified entity collection.

Function signature and example:

1 list(entityCollectionId: string, request?: TwelvelabsApi.entityCollections.EntitiesListRequest, requestOptions?: Entities.RequestOptions): Promise<core.Page<TwelvelabsApi.Entity>>

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
`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<TwelvelabsApi.Entity> 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<this>`	Retrieves the next page and returns the updated `Page` object.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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

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:

1 create(entityCollectionId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Entity>;

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
`metadata`	`Record<string, unknown>`	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 a core.HttpResponsePromise<TwelvelabsApi.Entity> 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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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

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:

1 createBulk(entityCollectionId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateBulkRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.BulkCreateEntityResponse>

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<string, unknown>`	No

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.BulkCreateEntityResponse> 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

Retrieve an entity

Description: This method retrieves details about the specified entity.

Function signature and example:

1 retrieve(entityCollectionId: string, entityId: string, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Entity>

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 a core.HttpResponsePromise<TwelvelabsApi.Entity> 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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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

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:

1 update(entityCollectionId: string, entityId: string, request?: TwelvelabsApi.entityCollections.EntitiesUpdateRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Entity>

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<string, unknown>`	No	Updated metadata for the entity. If provided, this completely replaces the existing metadata.

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.Entity> 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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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

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:

1 delete(entityCollectionId: string, entityId: string, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<void>

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 a core.HttpResponsePromise<void> that resolves when the entity has been successfully deleted.

API Reference: Delete an entity

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:

1 createAssets(entityCollectionId: string, entityId: string, request: TwelvelabsApi.entityCollections.EntitiesCreateAssetsRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Entity>

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

The EntitiesCreateAssetsRequest interface contains an array of strings representing the asset IDs to be added to the entity.

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.Entity> 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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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

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:

1 deleteAssets(entityCollectionId: string, entityId: string, request: TwelvelabsApi.entityCollections.EntitiesDeleteAssetsRequest, requestOptions?: Entities.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.Entity>

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

The EntitiesDeleteAssetsRequest interface contains an array of strings representing the asset IDs to be removed from the entity.

Return value: Returns a core.HttpResponsePromise<TwelvelabsApi.Entity> 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.
`name`	`string`	The name of the entity.
`description`	`string`	A description of the entity.
`metadata`	`Record<string, unknown>`	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`.
`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