Chats - Meilisearch Documentation

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
  }'

Conversational search is still in early development. Conversational agents may occasionally hallucinate inaccurate and misleading information, so it is important to closely monitor it in production environments.

Authorization

When implementing conversational search, use an API key with access to both the search and chatCompletions actions such as the default chat API key. You may also use tenant tokens instead of an API key, provided you generate the tokens with a key that has access to the required actions. Chat queries only search the indexes its API key can access. The default chat API key has access to all indexes. To limit access, you must either create a new key, or generate a tenant token from the default chat API key.

Chat workspaces

Workspaces are groups of chat settings tailored towards specific use cases. You must configure at least on workspace to use chat completions.

Chat workspace object

{
  "uid": "WORKSPACE_NAME"
}

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

Chat workspace settings object

{
  "source": "PROVIDER",
  "orgId": null,
  "projectId": null,
  "apiVersion": null,
  "deploymentId": null,
  "baseUrl": null,
  "apiKey": "PROVIDER_API_KEY",
  "prompts": {
    "system": "Description of the general search context"
  }
}

`source`

Type: String
Default value: N/A
Description: Name of the chosen embeddings provider. Must be one of: "openAi", "azureOpenAi", "mistral", "gemini", or "vLlm"

`orgId`

Type: String
Default value: N/A
Description: Organization ID used to access the LLM provider. Required for Azure OpenAI, incompatible with other sources

`projectId`

Type: String
Default value: N/A
Description: Project ID used to access the LLM provider. Required for Azure OpenAI, incompatible with other sources

`apiVersion`

Type: String
Default value: N/A
Description: API version used by the LLM provider. Required for Azure OpenAI, incompatible with other sources

`deploymentId`

Type: String
Default value: N/A
Description: Deployment ID used by the LLM provider. Required for Azure OpenAI, incompatible with other sources

`baseUrl`

Type: String
Default value: N/A
Description: Base URL Meilisearch should target when sending requests to the embeddings provider. Must be the full URL preceding the /chat/completions fragment. Required for Azure OpenAI and vLLM

`apiKey`

Type: String
Default value: N/A
Description: API key to access the LLM provider. Optional for vLLM, mandatory for all other providers

`prompts`

Type: Object
Default value: N/A
Description: Prompts giving baseline context to the conversational agent. The prompts object accepts the following fields:

prompts.system: Default prompt giving the general usage context of the conversational search agent. Example: “You are a helpful bot answering questions on how to use Meilisearch”
prompts.searchDescription: An internal description of the Meilisearch chat tools. Use it to instruct the agent on how and when to use the configured tools. Example: “Tool for retrieving relevant documents. Use it when users ask for factual information, past records, or resources that might exist in indexed content.”
prompts.QParam: Description of expected user input and the desired output. Example: “Users will ask about Meilisearch. Provide short and direct keyword-style queries.”
prompts.IndexUidParam: Instructions describing each index the agent has access to and how to use them. Example: “If user asks about code or API or parameters, use the index called documentation.”

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 workspace.

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"
}

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. For security reasons, the apiKey field is obfuscated.

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

Example

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

Create a chat workspace and update chat workspace settings

PATCH

/chats/{workspace_uid}/settings

Configure the LLM provider and settings for a chat workspace. If a 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
`projectId`	String	Project ID for the LLM provider
`apiVersion`	String	API version for the LLM provider
`deploymentId`	String	Deployment ID for the LLM provider
`baseUrl`	String	Base URL for the provider
`apiKey`	String	API key for the LLM provider
`prompts`	Object	Prompts object containing system prompts and other configuration

Prompt parameters

Name	Type	Description
[`system]` (#prompts)	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

Request body

{
  "source": "openAi",
  "apiKey": "OPEN_AI_API_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

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

curl \
  -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "source": "azureOpenAi",
    "orgId": "your-azure-org-id",
    "apiVersion": "your-api-version",
    "deploymentId": "your-deployment-id",
    "apiKey": "your-azure-api-key",
    "baseUrl": "https://your-resource.openai.azure.com",
    "prompts": {
      "system": "You are a helpful customer support assistant."
    }
  }'

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

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

curl \
  -X PATCH 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "source": "vLlm",
    "baseUrl": "http://your-vllm-server:8000",
    "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 \
  -X DELETE 'http://localhost:7700/chats/customer-support/settings' \
  -H 'Authorization: Bearer MEILISEARCH_KEY'

Chat completions

After creating a workspace, you can use the chat completions API to create a conversational search agent.

Stream chat completions

POST

/chats/{workspace_uid}/chat/completions

Create a chat completions stream using Meilisearch’s OpenAI-compatible interface. This 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 the agent should use when generating responses
`messages`	Array	Yes	Array of message objects
`stream`	Boolean	No	Enable streaming responses. Must be `true` if specified

Meilisearch chat completions only supports streaming responses (stream: true).

Message object

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

`role`

Specifies the message origin: Meilisearch (system), the LLM provider (assistant), or user input (user)

`content`

String containing the 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 -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
  }'

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:7700/chats/customer-support',
  apiKey: 'DEFAULT_CHAT_KEY',
});

const stream = await client.chat.completions.create({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: 'What is Meilisearch?' }],
  stream: true,
});

for await (const chunk of stream) {
  console.log(chunk.choices[0]?.delta?.content || '');
}

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7700/chats/customer-support",
    api_key="DEFAULT_CHAT_KEY"
)

stream = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "What is Meilisearch?"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

​Authorization

​Chat workspaces

​Chat workspace object

​Chat workspace settings object

​source

​orgId

​projectId

​apiVersion

​deploymentId

​baseUrl

​apiKey

​prompts

​List chat workspaces

​Query parameters

​Response

​Example

Response: 200 Ok

​Get one chat workspace

​Path parameters

​Example

Response: 200 Ok

​Get chat workspace settings

​Path parameters

​Response: 200 OK

​Example

​Create a chat workspace and update chat workspace settings

​Path parameters

​Settings parameters

Prompt parameters

​Request body

​Response: 200 OK

​Examples

​Reset chat workspace settings

​Path parameters

​Response: 200 OK

​Example

​Chat completions

​Stream chat completions

​Path parameters

​Request body

​Message object

​role

​content

​Response

​Streaming response example

​Example

Authorization

Chat workspaces

Chat workspace object

Chat workspace settings object

`source`

`orgId`

`projectId`

`apiVersion`

`deploymentId`

`baseUrl`

`apiKey`

`prompts`

List chat workspaces

Query parameters

Response

Example

Response: `200 Ok`

Get one chat workspace

Path parameters

Example

Response: `200 Ok`

Get chat workspace settings

Path parameters

Response: `200 OK`

Example

Create a chat workspace and update chat workspace settings

Path parameters

Settings parameters

Request body

Response: `200 OK`

Examples

Reset chat workspace settings

Path parameters

Response: `200 OK`

Example

Chat completions

Stream chat completions

Path parameters

Request body

Message object

`role`

`content`

Response

Streaming response example

Example