---
title: "Create an entity"
method: POST
path: "/entity-collections/{entity_collection_id}/entities"
tags: ["entityCollections > entities"]
---

# Create an entity

`POST /entity-collections/{entity_collection_id}/entities`

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

## Path parameters

- `entity_collection_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- object
  - `name` string, required — The name of the entity. Make sure you use a succinct and descriptive name.
  - `description` string — An optional description of the entity.
  - `metadata` EntityCollectionsEntityCollectionIdEntitiesPostRequestBodyContentApplicationJsonSchemaMetadata — 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>
  - `asset_ids` string[], required — An array of asset IDs to associate with the entity. You must provide at least one value.

## Response `201`

The entity has been successfully created.

- Entity — An object that represents an entity with associated assets.
  - `_id` string — The unique identifier of the entity.
  - `entity_collection_id` 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` EntityMetadata — Custom metadata for the entity.
  - `asset_ids` string[] — 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_at` string, date-time — The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was created.
  - `updated_at` string, date-time — The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the entity was last updated.

## Other responses

- `400` — The request has failed.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/5dbd6e8473c9/schema)