v3

latestOpenAPI 3.1.02026-07-3197486526.1 KB
knowledgeStores

Search a knowledge store

This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance.

Provide your natural-language query in the query.text field. Use the filter parameter to choose which items to search: by type of item (the asset_type field) or by specific items (the item_id field). Use the optional search_options parameter to control how videos are matched (by visual content, audio, or both). If you omit it, videos are matched on their visual content. Images are always matched on their visual content.

By default, each result is an individual match: a video clip or an image. Set the group_by parameter to item to group clips under their parent item.

<Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>
post/knowledge-stores/{knowledge_store_id}/search

Path parameters

knowledge_store_idstring required

The unique identifier of the knowledge store.

Headers

x-api-keystring required

Your API key.

<Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request body

group_by'none' | 'item'

Controls how the platform groups matches in the response.

  • none: Returns individual matches ordered by relevance.
  • item: Groups matches under their parent item.

Default: none.

page_sizeinteger

The maximum number of results per page. A result is one entry in the data array. With the group_by parameter set to its default of none, each result is an individual match: a video clip or an image. When set to item, each result is one item: a video with all its matching clips, or an image.

Default: 10. Max: 50.

page_tokenstring

Pagination token used to retrieve the next page of results. Omit it on the first request. To fetch the next page, set it to the next_page_token field returned in the previous response and send the request again.

A malformed or unrecognized token returns a 400 error. A token that has expired returns a 410 error (make a new search request to obtain a fresh page token).

include_metadataboolean

Set to true to include metadata in each result. Each result includes a metadata object with a system field (platform-derived file properties such as duration and resolution) and a user field (metadata you attached to the item).

Response

The search completed successfully.

next_page_tokenstring

The unique identifier of the next page.