Chats

Use the chat completion API to create conversational search experiences using LLM technology

The /chats route enables AI-powered conversational search by integrating Large Language Models (LLMs) with your Meilisearch data.

This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it:

curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "chatCompletions": true
  }'

When you enable the chat route for the first time, Meilisearch creates a new API key named “Default Chat API Key”.

Authorization

When working with a secure Meilisearch instance, Use an API key with access to both the search and chatCompletions actions, such as the default chat API key.

Chat queries only search indexes its API key can access. The default chat API key has access to all indexes.

Chat workspace object

{
  "uid": "WORKSPACE_NAME"
}

Name	Type	Description
uid	String	Unique identifier for the chat completions workspace

List chat workspaces

GET

/chats

List all chat workspaces. Results can be paginated by using the offset and limit query parameters.

Query parameters

Query parameter	Description	Default value
offset	Number of workspaces to skip	0
limit	Number of workspaces to return	20

Response

Name	Type	Description
results	Array	An array of workspaces
offset	Integer	Number of workspaces skipped
limit	Integer	Number of workspaces returned
total	Integer	Total number of workspaces

Example

  curl \
    -X GET 'MEILISEARCH_URL/chats?limit=3'

Response: 200 Ok

{
  "results": [
    { "uid": "WORKSPACE_1" },
    { "uid": "WORKSPACE_2" },
    { "uid": "WORKSPACE_3" }
  ],
  "offset": 0,
  "limit": 20,
  "total": 3
}

Get one chat workspace

GET

/chats/{workspace_uid}

Get information about a workshop.

Path parameters

Name	Type	Description
workspace_uid *	String	uid of the requested index

Example

  curl \
    -X GET 'MEILISEARCH_URL/chats/WORKSPACE_UID'

Response: 200 Ok

{
  "uid": "WORKSPACE_UID"
}

Chat workspace settings

Chat workspace settings object

{
  "source": "openAi",
  "orgId": null,
  "projectId": null,
  "apiVersion": null,
  "deploymentId": null,
  "baseUrl": null,
  "apiKey": "sk-abc...",
  "prompts": {
    "system": "You are a helpful assistant that answers questions based on the provided context."
  }
}

The prompts object

Name	Type	Description
system	String	A prompt added to the start of the conversation to guide the LLM
searchDescription	String	A prompt to explain what the internal search function does
searchQParam	String	A prompt to explain what the q parameter of the search function does and how to use it
searchIndexUidParam	String	A prompt to explain what the indexUid parameter of the search function does and how to use it

Get chat workspace settings

GET

/chats/{workspace_uid}/settings

Retrieve the current settings for a chat workspace.

Path parameters

Name	Type	Description
workspace_uid	String	The workspace identifier

Response: 200 OK

Returns the settings object without the apiKey field.

{
  "source": "openAi",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}

Example

cURL

curl \
  -X GET 'http://localhost:7700/chats/WORKSPACE_UID/settings' \
  -H 'Authorization: Bearer MASTER_KEY'

Update chat workspace settings

PATCH

/chats/{workspace_uid}/settings

Configure the LLM provider and settings for a chat workspace.

If the workspace does not exist, querying this endpoint will create it.

Path parameters

Name	Type	Description
workspace_uid	String	The workspace identifier

Settings parameters

Name	Type	Description
source	String	LLM source: "openAi", "azureOpenAi", "mistral", "gemini", or "vLlm"
orgId	String	Organization ID for the LLM provider (required for azureOpenAi)
projectId	String	Project ID for the LLM provider
apiVersion	String	API version for the LLM provider (required for azureOpenAi)
deploymentId	String	Deployment ID for the LLM provider (required for azureOpenAi)
baseUrl	String	Base URL for the provider (required for azureOpenAi and vLlm)
apiKey	String	API key for the LLM provider (optional for vLlm)
prompts	Object	Prompts object containing system prompts and other configuration

Request body

{
  "source": "openAi",
  "apiKey": "OPEN_AI_SECURITY_KEY",
  "prompts": {
    "system": "DEFAULT CHAT INSTRUCTIONS"
  }
}

All fields are optional. Only provided fields will be updated.

Response: 200 OK

Returns the updated settings object. apiKey is write-only and will not be returned in the response.

Examples

openAi

curl \
  -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "source": "openAi",
    "apiKey": "sk-abc...",
    "prompts": {
      "system": "You are a helpful customer support assistant."
    }
  }'

Reset chat workspace settings

DELETE

/chats/{workspace_uid}/settings

Reset a chat workspace’s settings to its default values.

Path parameters

Name	Type	Description
workspace_uid	String	The workspace identifier

Response: 200 OK

Returns the settings object without the apiKey field.

{
  "source": "openAi",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}

Example

cURL

curl \
  -X DELETE 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MASTER_KEY'

Chat completions

POST

/chats/{workspace_uid}/chat/completions

Create a chat completion using Meilisearch’s OpenAI-compatible interface. The endpoint searches relevant indexes and generates responses based on the retrieved content.

Path parameters

Name	Type	Description
workspace	String	The chat completion workspace unique identifier (uid)

Request body

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "What are the main features of Meilisearch?"
    }
  ],
  "stream": true
}

Name	Type	Required	Description
model	String	Yes	Model to use and will be related to the source LLM in the workspace settings
messages	Array	Yes	Array of message objects with role and content
stream	Boolean	No	Enable streaming responses (default: true)

Currently, only streaming responses (stream: true) are supported.

Message object

Name	Type	Description
role	String	Message role: "system", "user", or "assistant"
content	String	Message content

Response

The response follows the OpenAI chat completions format. For streaming responses, the endpoint returns Server-Sent Events (SSE).

Streaming response example

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Meilisearch"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Example

cURL

curl -N \
  -X POST 'http://localhost:7700/chats/customer-support/chat/completions' \
  -H 'Authorization: Bearer DEFAULT_CHAT_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "user",
        "content": "What is Meilisearch?"
      }
    ],
    "stream": true
  }'