entityCollections > entities

Create an entity

Changed on

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

post/entity-collections/{entity_collection_id}/entities

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/entity-collections/{entity_collection_id}/entities
  • Auth: API key in header x-api-key

Path parameters

entity_collection_idstring required

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

Request body

namestring required

The name of the entity. Make sure you use a succinct and descriptive name.

descriptionstring

An optional description of the entity.

metadataEntityCollectionsEntityCollectionIdEntitiesPostRequestBodyContentApplicationJsonSchemaMetadata

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:

{
  "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>
asset_idsstring[] required

An array of asset IDs to associate with the entity. You must provide at least one value.

Response

The entity has been successfully created.

_idstring

The unique identifier of the entity.

entity_collection_idstring

The unique identifier of the entity collection this entity belongs to.

namestring

The name of the entity.

descriptionstring

A description of the entity.

metadataEntityMetadata

Custom metadata for the entity.

asset_idsstring[]

An array of asset IDs associated with the entity.

status'processing' | 'ready'

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.
created_atstring date-time

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

updated_atstring date-time

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

Changes

  • b8591e05c0baRevision changes
    • warning

      deleted the header request parameter x-api-key

    • info

      the endpoint scheme security x-api-key was added to the API

  • 6205c7327cdeRevision changes
    • info

      api operation id create removed and replaced with entityCollections_entities_create