The knowledge store item object

A knowledge store item is an asset added to a knowledge store for processing. You can use it in different workflows once its status is ready.

The object is composed of the following fields:

• _id: A string representing the unique identifier of the knowledge store item.
• asset_type: A string indicating the type of item. It can take one of the following values:
  • video: A video item.
  • image: An image item.
• asset_id: A string representing the unique identifier of the source asset.
• status: A string indicating the processing status of the item. See the Item statuses section for the meaning of each value.
• system_metadata: An object containing system-generated metadata for the source asset. The shape of this object depends on the value of the asset_type field. For the full structure, see the system_metadata field on the Retrieve a knowledge store item page.
• metadata: An object containing the custom metadata of the source asset. Keys are strings; each value is a string, a number, a boolean, or an array of strings. The platform updates it when the user-defined metadata of the asset changes. To change it, use the PATCH method of the /assets/{asset_id}/user-metadata endpoint. To set custom metadata for the knowledge store item only, use item_metadata.
• item_metadata: An object containing the custom metadata of the knowledge store item. Keys are strings; each value is a string, a number, a boolean, or an array of strings. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the metadata field and in the item_metadata field. You set it when you create the item or change it with the PATCH or PUT method of the /knowledge-stores/{knowledge_store_id}/items/{item_id}/item-metadata endpoint. This field is absent when no item metadata has been set.
• enriched_metadata: An object containing metadata that the platform extracts from the whole item, as defined by the enrichment configuration of the knowledge store. It contains the properties that have the granularity keyword set to video for a video, or to image for an image. Properties that have the granularity keyword set to shot do not appear in this field. Keys are the property names; each value matches its property definition. A property with no value is omitted. The field is present only when the item is ready and contains at least one value.
• created_at: A string representing the date and time, in the RFC 3339 format, when the item was created.
• updated_at: A string representing the date and time, in the RFC 3339 format, when the item was last updated.

Item statuses

The status field of a knowledge store item has one of the following values:

• queued: The item has been submitted and is waiting to be processed.
• pending: The item has been dispatched and is waiting for available processing capacity.
• processing: The item is being processed.
• ready: The item has been successfully processed.
• failed: The item processing has failed.

Custom metadata field names

A knowledge store item has two sets of custom metadata: the custom metadata of the source asset and the custom metadata of the knowledge store item. The table shows the name of each set in each place.

A user_metadata key in a search filter matches the value in either set. For a metadata.<key> value of the sort_by parameter, the platform sorts by the value in the custom metadata of the knowledge store item. If that set has no value for the key, the platform uses the value in the custom metadata of the source asset.

Examples

Each example shows a populated knowledge store item.

{
  "_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
  "asset_type": "video",
  "asset_id": "6298d673f1090f1100476d4c",
  "status": "ready",
  "system_metadata": {
    "asset_type": "video",
    "filename": "01.mp4",
    "duration": 531.998133,
    "fps": 29.97,
    "width": 1920,
    "height": 1080,
    "codec_name": "h264",
    "size": 65749715
  },
  "metadata": {
    "project": "Q1 review"
  },
  "item_metadata": {
    "reviewer": "jane"
  },
  "enriched_metadata": {
    "brand": "Acme"
  },
  "created_at": "2026-05-12T16:53:59Z",
  "updated_at": "2026-05-12T16:55:59Z"
}