API ReferenceManage entities

Create an entity

This method creates an entity within a specified entity collection. Each entity must be associated with at least one asset.

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-key" target="_blank">API Key</a> page. </Note>

Path parameters

entity_collection_idstringRequired
The unique identifier of the entity collection in which to create the entity.

Request

This endpoint expects an object.
namestringRequired
The name of the entity. Make sure you use a succinct and descriptive name.
asset_idslist of stringsRequired
An array of asset IDs to associate with the entity. You must provide at least one value.
descriptionstringOptional
An optional description of the entity.
metadataobjectOptional
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`. **Example**: ```json { "sport": "soccer", "teamId": 42, "performanceScore": 8.7, "isActive": true } ``` <Note title="Note"> To store complex data types such as objects or arrays, convert them to string values before including them in the metadata. </Note>

Response

The entity has been successfully created.
_idstring or null
The unique identifier of the entity.
namestring or null
The name of the entity.
descriptionstring or null
A description of the entity.
metadataobject or null
Custom metadata for the entity.
asset_idslist of strings or null
An array of asset IDs associated with the entity.
statusenum or null
The current status of the entity creation process. **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.
Allowed values:
created_atstring or nullformat: "date-time"

The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created.

updated_atstring or nullformat: "date-time"

The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated.

Errors