POST /accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/search

Executes a semantic search query against an AI Search instance to find relevant indexed content.

Servers

https://api.cloudflare.com/client/v4

Path parameters

Name	Type	Required	Description
`id`	String	Yes	AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.
`name`	String	Yes	Namespace name
`account_id`	String	Yes

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`ai_search_options`	Object	No
`ai_search_options.reranking`	Object	No
`ai_search_options.reranking.match_threshold`	Number	No	Default value: 0.4
`ai_search_options.reranking.enabled`	Boolean	No
`ai_search_options.reranking.model`		No
`ai_search_options.query_rewrite`	Object	No
`ai_search_options.query_rewrite.enabled`	Boolean	No
`ai_search_options.query_rewrite.model`		No
`ai_search_options.query_rewrite.rewrite_prompt`	String	No
`ai_search_options.cache`	Object	No
`ai_search_options.cache.cache_threshold`	String	No	Valid values: `"flexible_friend"` `"super_strict_match"` `"anything_goes"` `"close_enough"`
`ai_search_options.cache.enabled`	Boolean	No
`ai_search_options.retrieval`	Object	No
`ai_search_options.retrieval.filters`	Object	No
`ai_search_options.retrieval.boost_by[]`	Array	No	Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.
`ai_search_options.retrieval.boost_by[].field`	String	Yes	Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support asc/desc directions; text/boolean fields support exists/not_exists.
`ai_search_options.retrieval.boost_by[].direction`	String	No	Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional �� defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Valid values: `"exists"` `"not_exists"` `"desc"` `"asc"`
`ai_search_options.retrieval.context_expansion`	Integer	No	Default value: 0
`ai_search_options.retrieval.retrieval_type`	String	No	Valid values: `"hybrid"` `"vector"` `"keyword"`
`ai_search_options.retrieval.fusion_method`	String	No	Valid values: `"max"` `"rrf"`
`ai_search_options.retrieval.match_threshold`	Number	No	Default value: 0.4
`ai_search_options.retrieval.keyword_match_mode`	String	No	Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. Defaults to 'and'. Valid values: `"and"` `"or"` Default value: "and"
`ai_search_options.retrieval.max_num_results`	Integer	No	Default value: 10
`ai_search_options.retrieval.return_on_failure`	Boolean	No	Default value: true
`query`	String	No	A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.
`messages[]`	Array	No
`messages[].content`	String	Yes
`messages[].role`	String	Yes	Valid values: `"developer"` `"assistant"` `"tool"` `"system"` `"user"`

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.