Skip to content

Commit 3f96048

Browse files
guimachiavelliguimachiavelli
committed
polish chat reference
1 parent 5446d6d commit 3f96048

File tree

1 file changed

+179
-125
lines changed

1 file changed

+179
-125
lines changed

‎reference/api/chats.mdx‎

Lines changed: 179 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,16 @@ curl \
2020
}'
2121
```
2222

23+
When you enable the chat route for the first time, Meilisearch creates a new API key named "Default Chat API Key".
2324
</Note>
2425

25-
## Chat completions workspace object
26+
## Authorization
27+
28+
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.
29+
30+
Chat queries only search indexes its API key can access. The default chat API key has access to all indexes.
31+
32+
## Chat workspace object
2633

2734
```json
2835
{
@@ -34,18 +41,80 @@ curl \
3441
| :---------- | :----- | :--------------------------------------------------- |
3542
| **`uid`** | String | Unique identifier for the chat completions workspace |
3643

37-
## Update chat workspace settings
44+
## List chat workspaces
3845

39-
<RouteHighlighter method="PUT" path="/chats/{workspace}/settings" />
46+
<RouteHighlighter method="GET" path="/chats" />
4047

41-
<RouteHighlighter method="PATCH" path="/chats/{workspace}/settings" />
48+
List all chat workspaces. Results can be paginated by using the `offset` and `limit` query parameters.
4249

43-
Configure the LLM provider and settings for a chat workspace.
50+
### Query parameters
51+
52+
| Query parameter | Description | Default value |
53+
| :-------------- | :----------------------------- | :------------ |
54+
| **`offset`** | Number of workspaces to skip | `0` |
55+
| **`limit`** | Number of workspaces to return | `20` |
56+
57+
### Response
58+
59+
| Name | Type | Description |
60+
| :------------ | :------ | :----------------------------------- |
61+
| **`results`** | Array | An array of [workspaces](#chat-workspace-object) |
62+
| **`offset`** | Integer | Number of workspaces skipped |
63+
| **`limit`** | Integer | Number of workspaces returned |
64+
| **`total`** | Integer | Total number of workspaces |
65+
66+
### Example
67+
68+
```sh
69+
curl \
70+
-X GET 'MEILISEARCH_URL/chats?limit=3'
71+
```
72+
73+
#### Response: `200 Ok`
74+
75+
```json
76+
{
77+
"results": [
78+
{ "uid": "WORKSPACE_1" },
79+
{ "uid": "WORKSPACE_2" },
80+
{ "uid": "WORKSPACE_3" }
81+
],
82+
"offset": 0,
83+
"limit": 20,
84+
"total": 3
85+
}
86+
```
87+
88+
## Get one chat workspace
89+
90+
<RouteHighlighter method="GET" path="/chats/{workspace_uid}" />
91+
92+
Get information about a workshop.
93+
94+
### Path parameters
95+
96+
| Name | Type | Description |
97+
| :---------------- | :----- | :------------------------------------------------------------------------ |
98+
| **`workspace_uid`** * | String | `uid` of the requested index |
99+
100+
### Example
101+
102+
```sh
103+
curl \
104+
-X GET 'MEILISEARCH_URL/chats/WORKSPACE_UID'
105+
```
44106

45-
Both `PUT` and `PATCH` methods are supported. `PUT` replaces the entire configuration, while `PATCH` updates only the provided fields.
107+
#### Response: `200 Ok`
46108

47-
The first call to either method will create the workspace UID if it doesn't already exist.
109+
```json
110+
{
111+
"uid": "WORKSPACE_UID"
112+
}
113+
```
114+
115+
## Chat workspace settings
48116

117+
### Chat workspace settings object
49118

50119
```json
51120
{
@@ -62,13 +131,67 @@ The first call to either method will create the workspace UID if it doesn't alre
62131
}
63132
```
64133

65-
### Path parameters
134+
#### The prompts object
135+
136+
| Name | Type | Description |
137+
| :------------------------ | :----- | :---------------------------------------------------------------- |
138+
| **`system`** | String | A prompt added to the start of the conversation to guide the LLM |
139+
| **`searchDescription`** | String | A prompt to explain what the internal search function does |
140+
| **`searchQParam`** | String | A prompt to explain what the `q` parameter of the search function does and how to use it |
141+
| **`searchIndexUidParam`** | String | A prompt to explain what the `indexUid` parameter of the search function does and how to use it |
142+
143+
### Get chat settings
144+
145+
<RouteHighlighter method="GET" path="/chats/{workspace_uid}/settings" />
146+
147+
Retrieve the current settings for a chat workspace.
148+
149+
#### Path parameters
66150

67151
| Name | Type | Description |
68152
| :-------------- | :----- | :----------------------------------- |
69-
| **`workspace`** | String | The workspace identifier |
153+
| **`workspace_uid`** | String | The workspace identifier |
154+
155+
#### Response: `200 OK`
156+
157+
Returns the settings object without the `apiKey` field.
158+
159+
```json
160+
{
161+
"source": "openAi",
162+
"prompts": {
163+
"system": "You are a helpful assistant."
164+
}
165+
}
166+
```
167+
168+
#### Example
70169

71-
### Settings parameters
170+
<CodeGroup>
171+
172+
```bash cURL
173+
curl \
174+
-X GET 'http://localhost:7700/chats/WORKSPACE_UID/settings' \
175+
-H 'Authorization: Bearer MASTER_KEY'
176+
```
177+
178+
</CodeGroup>
179+
180+
### Update chat workspace settings
181+
182+
<RouteHighlighter method="PATCH" path="/chats/{workspace_uid}/settings" />
183+
184+
Configure the LLM provider and settings for a chat workspace.
185+
186+
If the workspace does not exist, querying this endpoint will create it.
187+
188+
#### Path parameters
189+
190+
| Name | Type | Description |
191+
| :-------------- | :----- | :----------------------------------- |
192+
| **`workspace_uid`** | String | The workspace identifier |
193+
194+
#### Settings parameters
72195

73196
| Name | Type | Description |
74197
| :---------------- | :----- | :---------------------------------------------------------------------------- |
@@ -81,34 +204,25 @@ The first call to either method will create the workspace UID if it doesn't alre
81204
| **`apiKey`** | String | API key for the LLM provider (optional for vLlm) |
82205
| **`prompts`** | Object | Prompts object containing system prompts and other configuration |
83206

84-
### The prompts object
85-
86-
| Name | Type | Description |
87-
| :------------------------ | :----- | :---------------------------------------------------------------- |
88-
| **`system`** | String | A prompt added to the start of the conversation to guide the LLM |
89-
| **`searchDescription`** | String | A prompt to explain what the internal search function does |
90-
| **`searchQParam`** | String | A prompt to explain what the `q` parameter of the search function does and how to use it |
91-
| **`searchIndexUidParam`** | String | A prompt to explain what the `indexUid` parameter of the search function does and how to use it |
92-
93-
### Request body
207+
#### Request body
94208

95209
```json
96210
{
97211
"source": "openAi",
98-
"apiKey": "sk-...",
212+
"apiKey": "OPEN_AI_SECURITY_KEY",
99213
"prompts": {
100-
"system": "You are a helpful assistant."
214+
"system": "DEFAULT CHAT INSTRUCTIONS"
101215
}
102216
}
103217
```
104218

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

107-
### Response: `200 OK`
221+
#### Response: `200 OK`
108222

109-
Returns the updated settings object. Note that `apiKey` is write-only and will not be returned in the response.
223+
Returns the updated settings object. `apiKey` is write-only and will not be returned in the response.
110224

111-
### Examples
225+
#### Examples
112226

113227
<CodeGroup>
114228

@@ -188,11 +302,48 @@ curl \
188302

189303
</CodeGroup>
190304

305+
### Reset chat workspace settings
306+
307+
<RouteHighlighter method="DELETE" path="/chats/{workspace_uid}/settings" />
308+
309+
Reset a chat workspace's settings to its default values.
310+
311+
#### Path parameters
312+
313+
| Name | Type | Description |
314+
| :-------------- | :----- | :----------------------------------- |
315+
| **`workspace_uid`** | String | The workspace identifier |
316+
317+
#### Response: `200 OK`
318+
319+
Returns the settings object without the `apiKey` field.
320+
321+
```json
322+
{
323+
"source": "openAi",
324+
"prompts": {
325+
"system": "You are a helpful assistant."
326+
}
327+
}
328+
```
329+
330+
#### Example
331+
332+
<CodeGroup>
333+
334+
```bash cURL
335+
curl \
336+
-X DELETE 'http://localhost:7700/chats/customer-support/settings' \
337+
-H 'Authorization: Bearer MASTER_KEY'
338+
```
339+
340+
</CodeGroup>
341+
191342
## Chat completions
192343

193-
<RouteHighlighter method="POST" path="/chats/{workspace}/chat/completions" />
344+
<RouteHighlighter method="POST" path="/chats/{workspace_uid}/chat/completions" />
194345

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

197348
### Path parameters
198349

@@ -222,7 +373,7 @@ Create a chat completion using the OpenAI-compatible interface. The endpoint sea
222373
| **`stream`** | Boolean | No | Enable streaming responses (default: `true`) |
223374

224375
<Warning>
225-
Currently, only streaming responses (`stream: true`) are supported. Non-streaming responses will be available in a future release.
376+
Currently, only streaming responses (`stream: true`) are supported.
226377
</Warning>
227378

228379
### Message object
@@ -308,100 +459,3 @@ for chunk in stream:
308459
```
309460
310461
</CodeGroup>
311-
312-
## Get chat settings
313-
314-
<RouteHighlighter method="GET" path="/chats/{workspace}/settings" />
315-
316-
Retrieve the current settings for a chat workspace.
317-
318-
### Path parameters
319-
320-
| Name | Type | Description |
321-
| :-------------- | :----- | :----------------------------------- |
322-
| **`workspace`** | String | The workspace identifier |
323-
324-
### Response: `200 OK`
325-
326-
Returns the settings object without the `apiKey` field.
327-
328-
```json
329-
{
330-
"source": "openAi",
331-
"prompts": {
332-
"system": "You are a helpful assistant."
333-
}
334-
}
335-
```
336-
337-
### Example
338-
339-
<CodeGroup>
340-
341-
```bash cURL
342-
curl \
343-
-X GET 'http://localhost:7700/chats/customer-support/settings' \
344-
-H 'Authorization: Bearer MASTER_KEY'
345-
```
346-
347-
</CodeGroup>
348-
349-
## List chat workspaces
350-
351-
<RouteHighlighter method="GET" path="/chats" />
352-
353-
List all available chat workspaces. Results can be paginated using query parameters.
354-
355-
### Query parameters
356-
357-
| Query parameter | Description | Default value |
358-
| :-------------- | :----------------------------- | :------------ |
359-
| **`offset`** | Number of workspaces to skip | `0` |
360-
| **`limit`** | Number of workspaces to return | `20` |
361-
362-
### Response
363-
364-
| Name | Type | Description |
365-
| :------------ | :------ | :---------------------------------------- |
366-
| **`results`** | Array | An array of chat workspace objects |
367-
| **`offset`** | Integer | Number of workspaces skipped |
368-
| **`limit`** | Integer | Number of workspaces returned |
369-
| **`total`** | Integer | Total number of workspaces |
370-
371-
### Example
372-
373-
<CodeGroup>
374-
375-
```bash cURL
376-
curl \
377-
-X GET 'http://localhost:7700/chats?limit=10' \
378-
-H 'Authorization: Bearer MASTER_KEY'
379-
```
380-
381-
</CodeGroup>
382-
383-
#### Response: `200 OK`
384-
385-
```json
386-
{
387-
"results": [
388-
{
389-
"uid": "customer-support"
390-
},
391-
{
392-
"uid": "internal-docs"
393-
}
394-
],
395-
"offset": 0,
396-
"limit": 10,
397-
"total": 2
398-
}
399-
```
400-
401-
## Authentication
402-
403-
The chat feature integrates with Meilisearch's authentication system:
404-
405-
- **Default Chat API Key**: A new default key is created when chat is enabled, with permissions to access chat endpoints
406-
- **Tenant tokens**: Fully supported for multi-tenant applications
407-
- **Index visibility**: Chat searches only indexes accessible with the provided API key

0 commit comments

Comments
 (0)