> ## Documentation Index
> Fetch the complete documentation index at: https://meilisearch-6b28dec2-mintlify-code-samples.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chats

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

export const RouteHighlighter = ({method, path}) => <div className={`routeHighlighter routeHighlighter--${method}`}>
    <div className="routeHighlighter__method">
      {method}
    </div>
    <div className="routeHighlighter__path">
      {path}
    </div>
  </div>;

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

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

  ```sh theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/experimental-features/' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "chatCompletions": true
    }'
  ```
</Note>

<Warning>
  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.
</Warning>

## 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](/learn/security/generate_tenant_token_sdk) 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

```json theme={null}
{
  "uid": "WORKSPACE_NAME"
}
```

| Name      | Type   | Description                                          |
| :-------- | :----- | :--------------------------------------------------- |
| **`uid`** | String | Unique identifier for the chat completions workspace |

### Chat workspace settings object

```json theme={null}
{
  "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<br />
**Default value**: N/A<br />
**Description**: Name of the chosen embeddings provider. Must be one of: `"openAi"`, `"azureOpenAi"`, `"mistral"`, `"gemini"`, or `"vLlm"`

#### `orgId`

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

#### `projectId`

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

#### `apiVersion`

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

#### `deploymentId`

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

#### `baseUrl`

**Type**: String<br />
**Default value**: N/A<br />
**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<br />
**Default value**: N/A<br />
**Description**: API key to access the LLM provider. Optional for vLLM, mandatory for all other providers

#### `prompts`

**Type**: Object<br />
**Default value**: N/A<br />
**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

<RouteHighlighter method="GET" path="/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](#chat-workspace-object) |
| **`offset`**  | Integer | Number of workspaces skipped                     |
| **`limit`**   | Integer | Number of workspaces returned                    |
| **`total`**   | Integer | Total number of workspaces                       |

#### Example

```sh theme={null}
  curl \
    -X GET 'MEILISEARCH_URL/chats?limit=3'
```

##### Response: `200 Ok`

```json theme={null}
{
  "results": [
    { "uid": "WORKSPACE_1" },
    { "uid": "WORKSPACE_2" },
    { "uid": "WORKSPACE_3" }
  ],
  "offset": 0,
  "limit": 20,
  "total": 3
}
```

### Get one chat workspace

<RouteHighlighter method="GET" path="/chats/{workspace_uid}" />

Get information about a workspace.

#### Path parameters

| Name                   | Type   | Description                  |
| :--------------------- | :----- | :--------------------------- |
| **`workspace_uid`** \* | String | `uid` of the requested index |

#### Example

```sh theme={null}
  curl \
    -X GET 'MEILISEARCH_URL/chats/WORKSPACE_UID'
```

##### Response: `200 Ok`

```json theme={null}
{
  "uid": "WORKSPACE_UID"
}
```

### Get chat workspace settings

<RouteHighlighter method="GET" path="/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.

```json theme={null}
{
  "source": "openAi",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}
```

#### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X GET 'http://localhost:7700/chats/WORKSPACE_UID/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY'
  ```
</CodeGroup>

### Create a chat workspace and update chat workspace settings

<RouteHighlighter method="PATCH" path="/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`](#source)             | String | LLM source: `"openAi"`, `"azureOpenAi"`, `"mistral"`, `"gemini"`, or `"vLlm"` |
| [`orgId`](#orgid)               | String | Organization ID for the LLM provider                                          |
| [`projectId`](#projectid)       | String | Project ID for the LLM provider                                               |
| [`apiVersion`](#apiversion)     | String | API version for the LLM provider                                              |
| [`deploymentId`](#deploymentid) | String | Deployment ID for the LLM provider                                            |
| [`baseUrl`](#baseurl)           | String | Base URL for the provider                                                     |
| [`apiKey`](#apikey)             | String | API key for the LLM provider                                                  |
| [`prompts`](#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`](#prompts)   | String | A prompt to explain what the internal search function does                                      |
| [`searchQParam`](#prompts)        | String | A prompt to explain what the `q` parameter of the search function does and how to use it        |
| [`searchIndexUidParam`](#prompts) | String | A prompt to explain what the `indexUid` parameter of the search function does and how to use it |

#### Request body

```json theme={null}
{
  "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

<CodeGroup>
  ```bash openAi theme={null}
  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."
      }
    }'
  ```

  ```bash azureOpenAi theme={null}
  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."
      }
    }'
  ```

  ```bash mistral theme={null}
  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."
      }
    }'
  ```

  ```bash gemini theme={null}
  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."
      }
    }'
  ```

  ```bash vLlm theme={null}
  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."
      }
    }'
  ```
</CodeGroup>

### Reset chat workspace settings

<RouteHighlighter method="DELETE" path="/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.

```json theme={null}
{
  "source": "openAi",
  "prompts": {
    "system": "You are a helpful assistant."
  }
}
```

#### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X DELETE 'http://localhost:7700/chats/customer-support/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY'
  ```
</CodeGroup>

## Chat completions

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

### Stream chat completions

<RouteHighlighter method="POST" path="/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

```json theme={null}
{
  "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](#message-object)             |
| **`stream`**   | Boolean | No       | Enable streaming responses. Must be `true` if specified |

<Warning>
  Meilisearch chat completions only supports streaming responses (`stream: true`).
</Warning>

### 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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Javascript OpenAI SDK theme={null}
  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 || '');
  }
  ```

  ```python Python OpenAI SDK theme={null}
  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="")
  ```
</CodeGroup>