---
title: Chat Completions
---
[Skip to content](#_top)
[API Reference](https://developers.cloudflare.com/api)
[AI Search](https://developers.cloudflare.com/api/resources/ai_search)
[Instances](https://developers.cloudflare.com/api/resources/ai_search/subresources/instances)
Copy Markdown
Open in **Claude**Open in **ChatGPT**Open in **Cursor**
---
**Copy Markdown****View as Markdown**
# Chat Completions
Deprecated
POST/accounts/{account\_id}/ai-search/instances/{id}/chat/completions
Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses.
Deprecated: use /accounts/{account\_id}/ai-search/namespaces/{name}/instances (and descendant paths) instead.
##### Security
API Token
The preferred authorization scheme for interacting with the Cloudflare API. Create a token.
**Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
**Example:**X-Auth-Email: user@example.com
The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
**Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### P ath ParametersExpand Collapse
account\_id: string
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>)
id: string
AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.
maxLength64
minLength1
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%20default%20%3E%20(param)%20id%20%3E%20(schema)>)
##### Body ParametersJSONExpand Collapse
messages: array of object {content, role }
content: stringor array of object {text, type } or object {image\_url, type } or object {file, type } or string
One of the following:
string
Link to this property
array of object {text, type } or object {image\_url, type } or object {file, type }
One of the following:
object {text, type }
text: string
minLength1
Link to this property
type: "text"
Link to this property
Link to this property
object {image\_url, type }
image\_url: object {url }
url: string
maxLength20971520
minLength1
Link to this property
Link to this property
type: "image\_url"
Link to this property
Link to this property
object {file, type }
file: object {filename, file\_data, file\_id }
filename: string
maxLength255
minLength1
Link to this property
file\_data: optional string
maxLength13981144
minLength1
Link to this property
file\_id: optional string
Link to this property
Link to this property
type: "file"
Link to this property
Link to this property
Link to this property
string
Link to this property
Link to this property
role: "system"or "developer"or "user"or 2 more
One of the following:
"system"
Link to this property
"developer"
Link to this property
"user"
Link to this property
"assistant"
Link to this property
"tool"
Link to this property
Link to this property
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%200%20%3E%20(param)%20messages%20%3E%20(schema)>)
ai\_search\_options: optional object {cache, custom\_metadata, query\_rewrite, 2 more }
cache: optional object {cache\_threshold, enabled }
cache\_threshold: optional "super\_strict\_match"or "close\_enough"or "flexible\_friend"or "anything\_goes"
One of the following:
"super\_strict\_match"
Link to this property
"close\_enough"
Link to this property
"flexible\_friend"
Link to this property
"anything\_goes"
Link to this property
Link to this property
enabled: optional boolean
Link to this property
Link to this property
custom\_metadata: optional map\[stringor numberor boolean]
Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys ‘ai-search’, ‘task’, ‘origin’, and keys beginning with ‘cf.’ are reserved.
One of the following:
string
Link to this property
number
Link to this property
boolean
Link to this property
Link to this property
query\_rewrite: optional object {enabled, model, rewrite\_prompt }
enabled: optional boolean
Link to this property
model: optional string
A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.
Link to this property
rewrite\_prompt: optional string
Link to this property
Link to this property
reranking: optional object {enabled, match\_threshold, model }
enabled: optional boolean
Link to this property
match\_threshold: optional number
maximum1
minimum0
Link to this property
model: optional string
Link to this property
Link to this property
retrieval: optional object {boost\_by, context\_expansion, filters, 6 more }
boost\_by: optional array of object {field, direction }
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.
field: string
Metadata field name to boost by. Use ‘timestamp’ for document freshness, or any custom\_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not\_exists); text/boolean fields only support exists/not\_exists.
maxLength64
minLength1
Link to this property
direction: optional "asc"or "desc"or "exists"or "not\_exists"
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.
One of the following:
"asc"
Link to this property
"desc"
Link to this property
"exists"
Link to this property
"not\_exists"
Link to this property
Link to this property
Link to this property
context\_expansion: optional number
maximum3
minimum0
Link to this property
filters: optional map\[unknown]
Link to this property
fusion\_method: optional "max"or "rrf"
One of the following:
"max"
Link to this property
"rrf"
Link to this property
Link to this property
keyword\_match\_mode: optional "and"or "or"
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. When omitted, falls back to the instance-level retrieval\_options.keyword\_match\_mode, then to ‘and’.
One of the following:
"and"
Link to this property
"or"
Link to this property
Link to this property
match\_threshold: optional number
maximum1
minimum0
Link to this property
max\_num\_results: optional number
maximum50
minimum1
Link to this property
retrieval\_type: optional "vector"or "keyword"or "hybrid"
One of the following:
"vector"
Link to this property
"keyword"
Link to this property
"hybrid"
Link to this property
Link to this property
return\_on\_failure: optional boolean
Link to this property
Link to this property
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%200%20%3E%20(param)%20ai_search_options%20%3E%20(schema)>)
model: optional string
A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%200%20%3E%20(param)%20model%20%3E%20(schema)>)
stream: optional boolean
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(method)%20chat_completions%20%3E%20(params)%200%20%3E%20(param)%20stream%20%3E%20(schema)>)
##### ReturnsExpand Collapse
choices: array of object {message, index }
message: object {content, role }
content: stringor array of object {text, type } or object {image\_url, type } or object {file, type } or string
One of the following:
string
Link to this property
array of object {text, type } or object {image\_url, type } or object {file, type }
One of the following:
object {text, type }
text: string
minLength1
Link to this property
type: "text"
Link to this property
Link to this property
object {image\_url, type }
image\_url: object {url }
url: string
maxLength20971520
minLength1
Link to this property
Link to this property
type: "image\_url"
Link to this property
Link to this property
object {file, type }
file: object {filename, file\_data, file\_id }
filename: string
maxLength255
minLength1
Link to this property
file\_data: optional string
maxLength13981144
minLength1
Link to this property
file\_id: optional string
Link to this property
Link to this property
type: "file"
Link to this property
Link to this property
Link to this property
string
Link to this property
Link to this property
role: "system"or "developer"or "user"or 2 more
One of the following:
"system"
Link to this property
"developer"
Link to this property
"user"
Link to this property
"assistant"
Link to this property
"tool"
Link to this property
Link to this property
Link to this property
index: optional number
Link to this property
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(model)%20instance_chat_completions_response%20%3E%20(schema)%20%3E%20(property)%20choices>)
chunks: array of object {id, score, text, 3 more }
id: string
Link to this property
score: number
maximum1
minimum0
Link to this property
text: string
Link to this property
type: string
Link to this property
item: optional object {key, metadata, timestamp }
key: string
Link to this property
metadata: optional map\[unknown]
Link to this property
timestamp: optional number
Link to this property
Link to this property
scoring\_details: optional object {fusion\_method, keyword\_rank, keyword\_score, 3 more }
fusion\_method: optional "rrf"or "max"
One of the following:
"rrf"
Link to this property
"max"
Link to this property
Link to this property
keyword\_rank: optional number
Link to this property
keyword\_score: optional number
minimum0
Link to this property
reranking\_score: optional number
maximum1
minimum0
Link to this property
vector\_rank: optional number
Link to this property
vector\_score: optional number
maximum1
minimum0
Link to this property
Link to this property
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(model)%20instance_chat_completions_response%20%3E%20(schema)%20%3E%20(property)%20chunks>)
id: optional string
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(model)%20instance_chat_completions_response%20%3E%20(schema)%20%3E%20(property)%20id>)
model: optional string
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(model)%20instance_chat_completions_response%20%3E%20(schema)%20%3E%20(property)%20model>)
object: optional string
[Link to this property](<#(resource)%20ai_search.instances%20%3E%20(model)%20instance_chat_completions_response%20%3E%20(schema)%20%3E%20(property)%20object>)
### Chat Completions
HTTP
HTTPTypeScriptPythonGoTerraform
```
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances/$ID/chat/completions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-d '{
"messages": [
{
"content": "string",
"role": "system"
}
]
}'
```
200 example
```
{
"choices": [
{
"message": {
"content": "string",
"role": "system"
},
"index": 0
}
],
"chunks": [
{
"id": "id",
"score": 0,
"text": "text",
"type": "type",
"item": {
"key": "key",
"metadata": {
"foo": "bar"
},
"timestamp": 0
},
"scoring_details": {
"fusion_method": "rrf",
"keyword_rank": 0,
"keyword_score": 0,
"reranking_score": 0,
"vector_rank": 0,
"vector_score": 0
}
}
],
"id": "id",
"model": "model",
"object": "object"
}
```
##### Returns Examples
200 example
```
{
"choices": [
{
"message": {
"content": "string",
"role": "system"
},
"index": 0
}
],
"chunks": [
{
"id": "id",
"score": 0,
"text": "text",
"type": "type",
"item": {
"key": "key",
"metadata": {
"foo": "bar"
},
"timestamp": 0
},
"scoring_details": {
"fusion_method": "rrf",
"keyword_rank": 0,
"keyword_score": 0,
"reranking_score": 0,
"vector_rank": 0,
"vector_score": 0
}
}
],
"id": "id",
"model": "model",
"object": "object"
}
```