Use these methods to add assets to a knowledge store as items, to tag moments and ranges of video items, and to organize items into named collections.

Knowledge store items

The KnowledgeStoreItemsClient class provides methods to add and manage the items in a knowledge store.

Create a knowledge store item

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

Asset size limits:

Video: Up to 10 GB
Images: Up to 32 MB

Function signature and example:

def create(
    self,
    knowledge_store_id: str,
    *,
    asset_id: str,
    asset_type: typing.Optional[KnowledgeStoreItemAssetType] = OMIT,
    item_metadata: typing.Optional[typing.Dict[str, KnowledgeStoreMetadataValue]] = OMIT,
    metadata: typing.Optional[typing.Dict[str, KnowledgeStoreMetadataValue]] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItem:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`asset_id`	`str`	Yes	The unique identifier of the asset to add to the knowledge store. If you uploaded the asset before your plan moved to the new billing, enable storage accounting for it before you add it to a knowledge store. Use `assets.enable_storage_accounting`.
`asset_type`	`typing.` `Optional` `[KnowledgeStore` `ItemAssetType]`	No	The type of item to create. Values: `video`, `image`.
`item_metadata`	`typing.` `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	No	Custom metadata for the item. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 50 key-value pairs.
`metadata`	`typing.` `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	No	Deprecated. Use `item_metadata` instead. The item stores the pairs in its `item_metadata` field and not in its `metadata` field. Send `item_metadata` or `metadata`, not both. A request that sets both returns a `400` error.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItem object. The KnowledgeStoreItem class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the knowledge store item.
`asset_type`	`KnowledgeStore` `ItemAssetType`	The type of item. Values: `video`, `image`.
`asset_id`	`Optional[str]`	The unique identifier of the source asset.
`status`	`Optional` `[KnowledgeStore` `ItemStatus]`	The processing status of the item. Values: `queued`, `pending`, `processing`, `ready`, `failed`. For the meaning of each value, see the Item statuses section on The knowledge store item object page.
`system_metadata`	`Optional` `[KnowledgeStore` `ItemSystemMetadata]`	System-generated metadata for the source asset. Its `asset_type` field always matches the item’s top-level `asset_type` field.
`metadata`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	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 `update_user_metadata` method of `client.assets`. To set custom metadata for the knowledge store item only, use `item_metadata`.
`item_metadata`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	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 `update_knowledge_store_item_metadata` or `replace_knowledge_store_item_metadata` methods of `client.knowledge_store_items`. This field is absent when no item metadata has been set.
`enriched_metadata`	`Optional[Dict[str, Optional[Any]]]`	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`	`Optional` `[datetime]`	The date and time when the item was created, in the RFC 3339 format.
`updated_at`	`Optional` `[datetime]`	The date and time when the item was last updated, in the RFC 3339 format.

API Reference

Create a knowledge store item.

Add assets to a knowledge store.

List knowledge store items

Description: This method returns a list of items in the specified knowledge store.

Function signature and example:

def list(
    self,
    knowledge_store_id: str,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    sort_by: typing.Optional[KnowledgeStoreItemsListRequestSortBy] = None,
    sort_option: typing.Optional[str] = None,
    status: typing.Optional[
        typing.Union[
            KnowledgeStoreItemsListRequestStatusItem,
            typing.Sequence[KnowledgeStoreItemsListRequestStatusItem],
        ]
    ] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[KnowledgeStoreItem]:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`page`	`typing.` `Optional[int]`	No	A number that identifies the page to retrieve. Default: `1`.
`page_limit`	`typing.` `Optional[int]`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`sort_by`	`typing.` `Optional` `[KnowledgeStore` `ItemsListRequestSortBy]`	No	The field to sort on. The following options are available: - `created_at`: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was created. - `updated_at`: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was last updated. Default: `created_at`.
`sort_option`	`typing.` `Optional[str]`	No	The sorting direction. The following options are available: - `asc` - `desc` Default: `desc`.
`status`	`typing.` `Optional` `[typing.Union` `[..., Sequence]]`	No	Filter by one or more item processing statuses. Values: `queued`, `pending`, `processing`, `ready`, `failed`. For the meaning of each value, see the Item statuses section on The knowledge store item object page. To filter by multiple statuses, pass a list.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a SyncPager[KnowledgeStoreItem] object that allows you to iterate through the paginated list of items. For the properties of each KnowledgeStoreItem object, see Create a knowledge store item.

API Reference

List knowledge store items.

Retrieve a knowledge store item

Description: This method retrieves the details of a specific knowledge store item.

Function signature and example:

def retrieve(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItem:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItem object. For its properties, see Create a knowledge store item.

API Reference

Retrieve a knowledge store item.

Delete a knowledge store item

Description: This method deletes the specified knowledge store item.

Function signature and example:

def delete(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

This method does not return a value.

API Reference

Delete a knowledge store item.

Update the item metadata

Description: 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 Replace the item metadata method instead.

Function signature and example:

def update_knowledge_store_item_metadata(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    item_metadata: typing.Dict[str, typing.Optional[KnowledgeStoreMetadataEditValue]],
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItem:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`item_metadata`	`typing.Dict[str,` `typing.Optional[Knowledge` `StoreMetadataEditValue]]`	Yes	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.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItem object. For its properties, see Create a knowledge store item.

API Reference

Update the item metadata.

Replace the item metadata

Description: This method replaces the entire item_metadata of the specified knowledge store item and returns the item. Unlike the Update the item metadata method, which merges your changes with the existing metadata, this method overwrites the stored value in full:

A key with a value creates or replaces that key.
A key you omit, or set to an empty string (""), an empty array ([]), or null, is removed.

To clear all item metadata, send an empty object ({}) in the item_metadata field. The metadata field of the item does not change.

Function signature and example:

def replace_knowledge_store_item_metadata(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    item_metadata: typing.Dict[str, typing.Optional[KnowledgeStoreMetadataEditValue]],
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItem:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`item_metadata`	`typing.Dict[str,` `typing.Optional[Knowledge` `StoreMetadataEditValue]]`	Yes	The complete `item_metadata` of the item after the request. Up to 50 pairs. 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, or an array of strings. 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.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItem object. For its properties, see Create a knowledge store item.

API Reference

Replace the item metadata.

Item tags

The KnowledgeStoreItemTagsClient class provides methods to tag moments and ranges of video items. A tag carries custom metadata.

Create an item tag

Description: This method tags a moment or a range of a video item and returns the tag. Set start_sec to tag a moment. Set start_sec and end_sec to tag a range. A video item holds up to 100 tags. The method returns a 422 error for an item that is not a video item, and when the item already holds 100 tags.

Function signature and example:

def create(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    start_sec: float,
    tag_metadata: typing.Dict[str, KnowledgeStoreMetadataValue],
    end_sec: typing.Optional[float] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemTag:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`start_sec`	`float`	Yes	The start of the tag, in seconds from the start of the video. The value must be 0 or greater. It must be less than the duration of the video.
`tag_metadata`	`typing.Dict[str,` `KnowledgeStore` `MetadataValue]`	Yes	The custom metadata of the tag, as key-value pairs. Send at least one key. Up to 50 pairs. 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, or an array of strings. A nested object, an array containing anything other than strings, and a null value 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.
`end_sec`	`typing.` `Optional[float]`	No	The end of the range, in seconds from the start of the video. It must be greater than `start_sec`. It must not exceed the duration of the video. Omit it, or send `None`, to tag a single moment.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemTag object. The KnowledgeStoreItemTag class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the item tag.
`knowledge_store_id`	`str`	The unique identifier of the knowledge store.
`item_id`	`str`	The unique identifier of the knowledge store item that holds the tag.
`start_sec`	`float`	The start of the tag, in seconds from the start of the video.
`end_sec`	`Optional[float]`	The end of the range, in seconds from the start of the video. The value is `None` for a tag on a single moment.
`tag_metadata`	`Dict` `[str, KnowledgeStore` `MetadataValue]`	The custom metadata of the tag. Keys are strings. Each value is a string, a number, a boolean, or an array of strings.
`created_at`	`Optional` `[datetime]`	The date and time when the tag was created, in the RFC 3339 format.
`updated_at`	`Optional` `[datetime]`	The date and time when the tag was last updated, in the RFC 3339 format.

API Reference

Create an item tag.

List item tags

Description: This method returns the tags of the specified knowledge store item. The platform sorts the tags by start_sec, earliest first. Tags with the same start_sec are sorted by id.

Function signature and example:

def list(
    self,
    knowledge_store_id: str,
    item_id: str,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[KnowledgeStoreItemTag]:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`page`	`typing.` `Optional[int]`	No	A number that identifies the page to retrieve. Default: `1`.
`page_limit`	`typing.` `Optional[int]`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a SyncPager[KnowledgeStoreItemTag] object that allows you to iterate through the paginated list of item tags. For the properties of each KnowledgeStoreItemTag object, see Create an item tag.

API Reference

List item tags.

Retrieve an item tag

Description: This method retrieves the details of a specific tag of a knowledge store item.

Function signature and example:

def retrieve(
    self,
    knowledge_store_id: str,
    item_id: str,
    tag_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemTag:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`tag_id`	`str`	Yes	The unique identifier of the item tag.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemTag object. For its properties, see Create an item tag.

API Reference

Retrieve an item tag.

Update an item tag

Description: This method updates the range or the tag_metadata of the specified tag and returns the tag. Send at least one field. A field you omit keeps its current value. To clear the end of the range, send end_sec as None. The tag becomes a single moment. The platform merges your changes to tag_metadata with the existing metadata:

A key with a value creates or replaces that key.
A key set to None 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 tag must keep at least one key in tag_metadata, and it holds up to 50 pairs. If the merged result breaks either limit, the request fails.

Function signature and example:

def update(
    self,
    knowledge_store_id: str,
    item_id: str,
    tag_id: str,
    *,
    start_sec: typing.Optional[float] = OMIT,
    end_sec: typing.Optional[float] = OMIT,
    tag_metadata: typing.Optional[typing.Dict[str, typing.Optional[KnowledgeStoreMetadataEditValue]]] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemTag:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`tag_id`	`str`	Yes	The unique identifier of the item tag.
`start_sec`	`typing.` `Optional[float]`	No	The new start of the tag, in seconds from the start of the video. The value must be 0 or greater. It must be less than the duration of the video. The tag must still end after it starts.
`end_sec`	`typing.` `Optional[float]`	No	The new end of the range, in seconds from the start of the video. It must be greater than `start_sec`. It must not exceed the duration of the video. Send `None` to clear the end, which turns a range into a single moment. Omit the field to keep the current end.
`tag_metadata`	`typing.` `Optional[Dict[str,` `Optional[Knowledge` `StoreMetadataEditValue]]]`	No	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 `None` to delete the key. A key you omit keeps its current value. A nested object and an array containing anything other than strings are rejected. The tag holds up to 50 pairs after the merge. 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.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemTag object. For its properties, see Create an item tag.

API Reference

Update an item tag.

Delete an item tag

Description: This method deletes the specified tag of a knowledge store item.

Function signature and example:

def delete(
    self,
    knowledge_store_id: str,
    item_id: str,
    tag_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`item_id`	`str`	Yes	The unique identifier of the knowledge store item.
`tag_id`	`str`	Yes	The unique identifier of the item tag.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

This method does not return a value.

API Reference

Delete an item tag.

Item collections

The KnowledgeStoreItemCollectionsClient class provides methods to organize items into named collections that you can reference together.

Create an item collection

Description: This method creates an item collection in the specified knowledge store. An item collection is a named collection of items. Use item collections to organize and reference subsets of items together.

Function signature and example:

def create(
    self,
    knowledge_store_id: str,
    *,
    name: str,
    description: typing.Optional[str] = OMIT,
    metadata: typing.Optional[typing.Dict[str, KnowledgeStoreMetadataValue]] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemCollection:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`name`	`str`	Yes	The name of the item collection. Must be unique within the knowledge store.
`description`	`typing.` `Optional[str]`	No	An optional description of the item collection.
`metadata`	`typing.` `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	No	Custom metadata for the item collection. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 10 key-value pairs.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemCollection object. The KnowledgeStoreItemCollection class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the item collection.
`knowledge_store_id`	`Optional[str]`	The unique identifier of the knowledge store this collection belongs to.
`name`	`Optional[str]`	The name of the item collection.
`description`	`Optional[str]`	The description of the item collection.
`metadata`	`Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	Custom metadata for the item collection. Keys are strings; each value is a string, a number, a boolean, or an array of strings.
`member_count`	`Optional[int]`	The number of items in the collection.
`created_at`	`Optional` `[datetime]`	The date and time when the item collection was created, in the RFC 3339 format.
`updated_at`	`Optional` `[datetime]`	The date and time when the item collection was last updated, in the RFC 3339 format.

API Reference

Create an item collection.

List item collections

Description: This method returns a list of the item collections in the specified knowledge store.

Function signature and example:

def list(
    self,
    knowledge_store_id: str,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    sort_by: typing.Optional[KnowledgeStoreItemCollectionsListRequestSortBy] = None,
    sort_option: typing.Optional[str] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[KnowledgeStoreItemCollection]:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`page`	`typing.` `Optional[int]`	No	A number that identifies the page to retrieve. Default: `1`.
`page_limit`	`typing.` `Optional[int]`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`sort_by`	`typing.` `Optional` `[KnowledgeStore` `ItemCollections` `ListRequestSortBy]`	No	The field to sort on. The following options are available: - `created_at`: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item collection was created. - `updated_at`: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item collection was last updated. - `name`: Sorts alphabetically by the name of the item collection. Default: `created_at`.
`sort_option`	`typing.` `Optional[str]`	No	The sorting direction. The following options are available: - `asc` - `desc` Default: `desc`.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a SyncPager[KnowledgeStoreItemCollection] object that allows you to iterate through the paginated list of item collections. For the properties of each KnowledgeStoreItemCollection object, see Create an item collection.

API Reference

List item collections.

Retrieve an item collection

Description: This method retrieves the details of a specific item collection.

Function signature and example:

def retrieve(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemCollection:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemCollection object. For its properties, see Create an item collection.

API Reference

Retrieve an item collection.

Update an item collection

Description: This method updates the name, description, and metadata fields of the specified item collection.

Function signature and example:

def update(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    name: typing.Optional[str] = OMIT,
    description: typing.Optional[str] = OMIT,
    metadata: typing.Optional[typing.Dict[str, KnowledgeStoreMetadataValue]] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemCollection:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`name`	`typing.` `Optional[str]`	No	The name of the item collection. Must be unique within the knowledge store.
`description`	`typing.` `Optional[str]`	No	An optional description of the item collection.
`metadata`	`typing.` `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]`	No	Custom metadata for the item collection. Keys are strings; values can be a string, a number, a boolean, or an array of strings. You can provide up to 10 key-value pairs. The provided object replaces the existing metadata in full, so include every key you want to keep and omit the ones you want to remove. To clear all metadata, set this field to an empty object (`{}`).
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemCollection object. For its properties, see Create an item collection.

API Reference

Update an item collection.

Delete an item collection

Description: This method deletes the specified item collection. The items themselves remain in the knowledge store.

Function signature and example:

def delete(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

This method does not return a value.

API Reference

Delete an item collection.

List items in an item collection

Description: This method returns a list of the items in the specified item collection.

Function signature and example:

def list_items(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> SyncPager[KnowledgeStoreItem]:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`page`	`typing.` `Optional[int]`	No	A number that identifies the page to retrieve. Default: `1`.
`page_limit`	`typing.` `Optional[int]`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a SyncPager[KnowledgeStoreItem] object that allows you to iterate through the paginated list of items in the collection. For the properties of each KnowledgeStoreItem object, see Create a knowledge store item.

API Reference

List items in an item collection.

Add items to an item collection

Description: This method adds one or more items to the specified item collection. This operation is idempotent — items already in the collection are skipped. Every identifier must reference an existing item in the knowledge store.

Function signature and example:

def add_items(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    item_ids: typing.Sequence[str],
    request_options: typing.Optional[RequestOptions] = None,
) -> KnowledgeStoreItemCollection:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`item_ids`	`typing.` `Sequence[str]`	Yes	The unique identifiers of the items to add to the collection. Include up to 500 identifiers per request.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a KnowledgeStoreItemCollection object. For its properties, see Create an item collection.

API Reference

Add items to an item collection.

Remove items from an item collection

Description: This method removes one or more items from the specified item collection. This operation is idempotent — identifiers that do not match a member of the collection are ignored. The items themselves remain in the knowledge store.

Function signature and example:

def remove_items(
    self,
    knowledge_store_id: str,
    collection_id: str,
    *,
    item_ids: typing.Sequence[str],
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters

Name	Type	Required	Description
`knowledge_store_id`	`str`	Yes	The unique identifier of the knowledge store.
`collection_id`	`str`	Yes	The unique identifier of the knowledge store item collection.
`item_ids`	`typing.` `Sequence[str]`	Yes	The unique identifiers of the items to remove from the collection. Include up to 500 identifiers per request.
`request_options`	`typing.` `Optional` `[RequestOptions]`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

This method does not return a value.

API Reference

Remove items from an item collection.

Knowledge store items

Create a knowledge store item

Parameters

Return value

API Reference

Related guide

List knowledge store items

Parameters

Return value

API Reference

Retrieve a knowledge store item

Parameters

Return value

API Reference

Delete a knowledge store item

Parameters

Return value

API Reference

Update the item metadata

Parameters

Return value

API Reference

Replace the item metadata

Parameters

Return value

API Reference

Item tags

Create an item tag

Parameters

Return value

API Reference

List item tags

Parameters

Return value

API Reference

Retrieve an item tag

Parameters

Return value

API Reference

Update an item tag

Parameters

Return value

API Reference

Delete an item tag

Parameters

Return value

API Reference

Item collections

Create an item collection

Parameters

Return value

API Reference

List item collections

Parameters

Return value

API Reference

Retrieve an item collection

Parameters

Return value

API Reference

Update an item collection

Parameters

Return value

API Reference

Delete an item collection

Parameters

Return value

API Reference

List items in an item collection

Parameters

Return value

API Reference

Add items to an item collection

Parameters

Return value

API Reference

Remove items from an item collection

Parameters

Return value

API Reference