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

# Add assets to an entity

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

## Request

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

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."

## Path parameters

- `entity_collection_id` string, required
- `entity_id` string, required

## Request body

- object
  - `asset_ids` string[], required: An array of asset IDs to add to the entity.

## Response `200`

The assets have been successfully added to the entity.

- 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.

## Changes

- **2026-09-17** `b8591e05c0ba`: 1 warning, 1 info
  - deleted the `header` request parameter `x-api-key`
  - the endpoint scheme security `x-api-key` was added to the API
- **2026-09-12** `6205c7327cde`: 1 info
  - api operation id `create-assets` removed and replaced with `entityCollections_entities_createAssets`
- **2026-07-31** `5dbd6e8473c9`: 1 warning
  - removed the optional property `docs_url` from the response with the `400` status

[Operation history](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/changes/entity-collections/:entity_collection_id/entities/:entity_id/assets/post.md)

---

[API](https://skmtc.dev/twelvelabs/apis/twelvelabs-api.md) - [All operations](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/revisions/c23c6e18fdd1?raw)