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.
This endpoint is rate-limited. For details, see the Rate limits page.
Authentication
Your API key.
You can find your API key on the API Keys page.
Path parameters
Request
Request body for searching a knowledge store.
To paginate, set the page_token parameter to the next_page_token field returned in the previous response and send the request again. The token identifies the original search, so any search fields you send are ignored.
Narrows results to specific items in the knowledge store.
Filter by type of item (the asset_type field) or by specific identifiers (the item_id field). Use eq to match a single value or in to match any value in a list. When you specify multiple fields, the platform applies all conditions together.
Examples:
{
"asset_type": {
"eq": "video"
}
}
{
"asset_type": {
"in": [
"video"
]
},
"item_id": {
"in": [
"ksi_069e9870-3c4d-7abc-9012-3456789abcde"
]
}
}
Omit the filter to search all items.
Specifies how videos are matched. Videos are the only type of item with configurable options, set in the search_options.video field. Images are always matched on their visual content and have no options to configure.
To choose which types of items to search, use the filter.asset_type field. If you provide options in the search_options.video field when the filter.asset_type field excludes videos, the platform returns a 400 error.
If you omit this field, videos are matched on their visual content.
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.
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.
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.
If a token is malformed or unrecognized, the platform returns a 400 error. If a token has expired, the platform returns a 410 error (make a new search request to obtain a fresh page token).
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 headers
The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.
Response
The video options applied to this search, including any defaults.
- When the search includes videos: this object contains a
videofield with the modalities used. - When the search is limited to images (the
filter.asset_typefield excludes videos): no video options apply, and this object is empty.
Any option you omit is returned with its default value. For example, the video field shows ["visual"] for modalities when you don't set search_options.video.
Pagination token for the next page. Pass this value as the page_token parameter in your next request to retrieve more results. Absent when no more pages exist.