---
title: "Create a knowledge store item"
method: POST
path: "/knowledge-stores/{knowledge_store_id}/items"
tags: ["knowledgeStoreItems"]
---

# Create a knowledge store item

`POST /knowledge-stores/{knowledge_store_id}/items`

This method adds an asset to a knowledge store for processing.
The operation is asynchronous. The item is created immediately with the `queued`
status and processed in the background.

The asset must not exceed 5 GB.

## Path parameters

- `knowledge_store_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- object
  - `asset_type` 'video' | 'image' — The type of item in the knowledge store.
  - `asset_id` string, required — The unique identifier of the asset to add to the knowledge store.
  - `metadata` object — Custom metadata for the item. Both keys and values must be strings.

## Response `202`

The item creation request has been accepted and is processing.

- KnowledgeStoreItem — A knowledge store item is an asset added to a knowledge store for processing. You can use it in downstream workflows once its `status` is `ready`.
  - `_id` string — The unique identifier of the knowledge store item.
  - `asset_type` 'video' | 'image', required — The type of item in the knowledge store.
  - `asset_id` string — The unique identifier of the source asset.
  - `status` 'queued' | 'pending' | 'processing' | 'ready' | 'failed' — The processing status of the item. For the meaning of each value, see the [Item statuses](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#item-statuses) section on **The knowledge store item object** page.
  - `system_metadata` union — System-generated media metadata for the source asset. Its `asset_type` field always matches the item's top-level `asset_type` field.
    - object — System-generated media metadata for a video item.
      - `asset_type` 'video', required — This field is always set to `video` for video items.
      - `filename` string — The original filename of the video.
      - `duration` number, double — The duration of the video in seconds.
      - `fps` number, double — The frame rate of the video in frames per second.
      - `width` integer — The width of the video in pixels.
      - `height` integer — The height of the video in pixels.
      - `codec_name` string — The codec used to encode the video.
      - `size` integer — The file size of the video in bytes.
    - object — System-generated media metadata for an image item.
      - `asset_type` 'image', required — This field is always set to `image` for image items.
      - `filename` string — The original filename of the image.
      - `width` integer — The width of the image in pixels.
      - `height` integer — The height of the image in pixels.
      - `codec_name` string — The codec used to encode the image.
      - `size` integer — The file size of the image in bytes.
  - `metadata` object — Custom metadata for the item.
  - `created_at` string, date-time — The date and time when the item was created, in the RFC 3339 format.
  - `updated_at` string, date-time — The date and time when the item was last updated, in the RFC 3339 format.

## 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)