Skip to navigation
Agents (Research preview)Knowledge store items

Update the item metadata

This method updates the item_metadata of the specified knowledge store item and returns the item. The platform merges your changes with the existing metadata:

  • A key with a value creates or replaces that key.
  • A key set to null deletes that key.
  • A key set to an empty string ("") or an empty array ([]) is ignored.
  • A key you omit from the request keeps its current value.

The metadata field of the item does not change. If the merged result contains more than 50 pairs, the request fails.

To replace all item metadata in a single call, use the PUT method of the /knowledge-stores/{knowledge_store_id}/items/{item_id}/item-metadata endpoint instead.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Path parameters

knowledge_store_idstringRequired
The unique identifier of the knowledge store.
item_idstringRequired
The unique identifier of the knowledge store item.

Request

This endpoint expects an object.
item_metadatamap from strings to nullable strings or integers or doubles or booleans or lists of stringsRequired

The keys to change. Send at least one key. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, an array of strings, or null to delete the key. A nested object and an array containing anything other than strings are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string.

Response

The item metadata has been successfully updated.
asset_typeenum
The type of item.
Allowed values:
_idstringOptional
The unique identifier of the knowledge store item.
asset_idstringOptional
The unique identifier of the source asset.
statusenumOptionalRead-only

The processing status of the item. For the meaning of each value, see the Item statuses section on The knowledge store item object page.

Allowed values:
system_metadataobjectOptionalRead-only

System-generated media metadata for the source asset. Its asset_type field always matches the item's top-level asset_type field.

metadatamap from strings to strings or integers or doubles or booleans or lists of stringsOptional

Custom metadata from 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 store metadata on the item alone, use item_metadata.

item_metadatamap from strings to strings or integers or doubles or booleans or lists of stringsOptional

Custom metadata stored on this item alone. Keys are strings; each value is a string, a number, a boolean, or an array of strings. The source asset never changes it, so the same key can have a different value in metadata and in item_metadata. 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. The field is absent when the item has no item metadata.

created_atstringOptionalformat: "date-time"
The date and time when the item was created, in the RFC 3339 format.
updated_atstringOptionalformat: "date-time"
The date and time when the item was last updated, in the RFC 3339 format.

Errors

400
Bad Request Error
404
Not Found Error