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.

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.

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.

cURL

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

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.

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.

Azure OpenAI example

Azure OpenAI requires additional fields for deployment configuration:

cURL

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

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:

cURL

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

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.

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

cURL

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

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.

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 guide for full documentation on description, documentTemplate, searchParameters, and other fields.

Verify workspace configuration

Retrieve the current settings for a workspace at any time:

cURL

curl \
  -X GET 'MEILISEARCH_URL/chats/WORKSPACE_NAME/settings' \
  -H "Authorization: Bearer MEILISEARCH_KEY"

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:

cURL

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

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

cURL

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

Next steps

• Stream chat responses to deliver answers token by token
• Configure guardrails to control the scope and quality of responses
• Reduce hallucination with system prompt engineering and few-shot prompting
• Consult the workspace settings API reference and the chat completions API reference for all available parameters