Chats

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

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. To limit chat access to specific indexes, you must either create a new key, or generate a tenant token from the default chat API key.

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

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_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."
    }
  }'

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

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

API reference

Errors

Authorization

Chat workspace object

List chat workspaces

Query parameters

Response

Example

Response: `200 Ok`

Get one chat workspace

Path parameters

Example

Response: `200 Ok`

Chat workspace settings

Chat workspace settings object

The prompts object

Get chat workspace settings

Path parameters

Response: `200 OK`

Example

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

Path parameters

Request body

Message object

Response

Streaming response example

Example

API reference

Errors

​Authorization

​Chat workspace object

​List chat workspaces

​Query parameters

​Response

​Example

​Response: 200 Ok

​Get one chat workspace

​Path parameters

​Example

​Response: 200 Ok

​Chat workspace settings

​Chat workspace settings object

​The prompts object

​Get chat workspace settings

​Path parameters

​Response: 200 OK

​Example

​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

​Path parameters

​Request body

​Message object

​Response

​Streaming response example

​Example

Authorization

Chat workspace object

List chat workspaces

Query parameters

Response

Example

Response: `200 Ok`

Get one chat workspace

Path parameters

Example

Response: `200 Ok`

Chat workspace settings

Chat workspace settings object

The prompts object

Get chat workspace settings

Path parameters

Response: `200 OK`

Example

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

Path parameters

Request body

Message object

Response

Streaming response example

Example