> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a chat workspace

> Set up a chat workspace with a system prompt, tools, and connected indexes for conversational search.

A chat workspace groups the chat settings tailored to a specific use case: the LLM provider credentials, the system prompt, and the search behavior. Workspaces are the entry point for conversational search. You must configure at least one workspace before the chat completions endpoint can serve requests. You can also create multiple workspaces targeting different use cases, such as a public-facing knowledge base and an internal support tool.

<Note>
  On Meilisearch Cloud, the default workspace name is `cloud`. Replace `WORKSPACE_NAME` with `cloud` in all API calls. If you need additional workspaces, contact us.
</Note>

## Create a workspace

Create a workspace by sending a `PATCH` request to `/chats/{workspace_uid}/settings`. If the workspace does not exist, Meilisearch creates it automatically.

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/chats/my-support-bot/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "source": "openAi",
      "apiKey": "YOUR_OPENAI_API_KEY",
      "prompts": {
        "system": "You are a helpful support assistant. Answer questions based only on the provided context."
      }
    }'
  ```
</CodeGroup>

The `workspace_uid` in the URL (in this example, `my-support-bot`) is a unique identifier you choose. Use a descriptive name that reflects the workspace's purpose.

## Configure the LLM provider

The `source` field determines which LLM provider Meilisearch uses. Each provider has slightly different requirements:

| Provider     | `source` value | Required fields                                         | Optional fields |
| ------------ | -------------- | ------------------------------------------------------- | --------------- |
| OpenAI       | `openAi`       | `apiKey`                                                | `baseUrl`       |
| Azure OpenAI | `azureOpenAi`  | `apiKey`, `baseUrl`, `orgId`, `projectId`, `apiVersion` | `deploymentId`  |
| Mistral      | `mistral`      | `apiKey`, `baseUrl`                                     |                 |
| vLLM         | `vLlm`         | `baseUrl`                                               | `apiKey`        |

A few provider-specific rules to keep in mind:

* `orgId`, `projectId`, and `apiVersion` are required for Azure OpenAI and are incompatible with every other `source`. Sending them with `openAi`, `mistral`, or `vLlm` is rejected.
* `baseUrl` is required for Azure OpenAI and vLLM. For Mistral it points to the Mistral API endpoint. For OpenAI it is optional and only needed when routing through a custom endpoint.
* `apiKey` is optional for vLLM (self-hosted deployments often run without authentication) and mandatory for every other provider.

<Warning>
  The `apiKey` field is write-only. Meilisearch stores it for outbound LLM calls but redacts it in every response from the workspace settings endpoint. Retrieving the settings will show an obfuscated placeholder rather than the real secret, so keep your own copy in a secure location. To rotate the key, `PATCH` the workspace with the new value.
</Warning>

### Azure OpenAI example

Azure OpenAI requires additional fields for deployment configuration:

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/chats/my-support-bot/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "source": "azureOpenAi",
      "apiKey": "YOUR_AZURE_API_KEY",
      "baseUrl": "https://your-resource.openai.azure.com",
      "deploymentId": "your-deployment-id",
      "apiVersion": "2024-02-01"
    }'
  ```
</CodeGroup>

## Configure the system prompt

The system prompt gives the conversational agent its baseline instructions. It controls the agent's behavior, tone, and scope. Set it through the `prompts.system` field:

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/chats/my-support-bot/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "prompts": {
        "system": "You are a customer support agent for an online bookstore. Only answer questions about books, orders, and shipping. If the user asks about unrelated topics, politely redirect them to the relevant support channel."
      }
    }'
  ```
</CodeGroup>

The `prompts` object accepts additional fields that help the LLM understand how to use Meilisearch's search capabilities:

| Field                 | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `system`              | Baseline instructions for the conversational agent                                     |
| `searchDescription`   | Describes the search function to the LLM, helping it understand when and how to search |
| `searchQParam`        | Describes the query parameter, guiding the LLM on how to formulate search queries      |
| `searchFilterParam`   | Describes the filter parameter, helping the LLM construct appropriate filters          |
| `searchIndexUidParam` | Describes the index UID parameter, guiding the LLM on which index to search            |

These fields provide additional context that improves how the agent formulates searches. For guidance on writing effective system prompts, see [configure guardrails](/capabilities/conversational_search/how_to/configure_guardrails).

## LLM provider parameters passthrough

Meilisearch forwards standard chat completion parameters directly to the configured LLM provider. This means you can include parameters like `temperature`, `top_p`, `frequency_penalty`, or `presence_penalty` in your [chat completions requests](/reference/api/chats/request-a-chat-completion) and Meilisearch will pass them through to the provider as-is.

For example, lowering `temperature` makes responses more deterministic and factual, while raising it produces more varied and creative outputs:

<CodeGroup>
  ```bash cURL theme={null}
  curl -N \
    -X POST 'MEILISEARCH_URL/chats/WORKSPACE_NAME/chat/completions' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "model": "PROVIDER_MODEL_UID",
      "messages": [
        {
          "role": "user",
          "content": "What are your return policies?"
        }
      ],
      "temperature": 0.2
    }'
  ```
</CodeGroup>

<Note>
  Available parameters and their behavior depend on the LLM provider you configured. Refer to your provider's documentation for the full list of supported parameters and their effects.
</Note>

## Configure indexes for chat

Before a workspace can search your data, each index must have its chat settings configured. See the dedicated [configure index chat settings](/capabilities/conversational_search/how_to/configure_index_chat_settings) guide for full documentation on `description`, `documentTemplate`, `searchParameters`, and other fields.

## Verify workspace configuration

Retrieve the current settings for a workspace at any time:

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X GET 'MEILISEARCH_URL/chats/WORKSPACE_NAME/settings' \
    -H "Authorization: Bearer MEILISEARCH_KEY"
  ```
</CodeGroup>

This returns the full configuration, including the provider and system prompt. Note that the `apiKey` value is redacted in the response for security.

## Update workspace settings

Update any workspace setting by sending a `PATCH` request with only the fields you want to change. Fields you omit remain unchanged:

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/chats/WORKSPACE_NAME/settings' \
    -H "Authorization: Bearer MEILISEARCH_KEY" \
    -H "Content-Type: application/json" \
    --data-binary '{ "apiKey": "your-valid-api-key" }'
  ```
</CodeGroup>

For example, to update only the system prompt without changing the provider:

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/chats/my-support-bot/settings' \
    -H 'Authorization: Bearer MEILISEARCH_KEY' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "prompts": {
        "system": "You are a helpful assistant for a tech documentation site. Always include code examples in your answers when relevant."
      }
    }'
  ```
</CodeGroup>

## Next steps

* [Stream chat responses](/capabilities/conversational_search/how_to/stream_chat_responses) to deliver answers token by token
* [Configure guardrails](/capabilities/conversational_search/how_to/configure_guardrails) to control the scope and quality of responses
* [Reduce hallucination](/capabilities/conversational_search/advanced/reduce_hallucination) with system prompt engineering and few-shot prompting
* Consult the [workspace settings API reference](/reference/api/chats/update-settings-of-a-chat-workspace) and the [chat completions API reference](/reference/api/chats/request-a-chat-completion) for all available parameters