Configuration

Prerequisites

• Witty microservice must be up & running and reachable from Witboost Core;
• Docs agent microservice must be up & running and reachable from Witboost Core.

How to install Witty & Docs agent microservices is described here Installing Witty

Configuring Witty via the Administration Panel

Navigate to Administration > Configuration > Witty to manage runtime AI settings without redeploying.

note

The Witty tab is visible only when the Witty module is enabled in your license. Access requires the platformSettingsEditPermission permission.

Enabling Witty

Witty can be enabled or disabled using the toggle in Administration > Configuration > Witty. When disabled, Witty's icon is hidden across the platform, and all Witty-related features are inaccessible. When enabled, you can configure the LLM and Embedder settings.

LLM Configuration

Witty needs a valid LLM model. The recommended way to configure the LLM model is through Administration > Configuration > Witty. In the LLM section:

1. Select azure_openai from the Provider dropdown (the only currently supported option).
2. Enter your API Key. After saving, only the last 4 characters will be visible — the key is encrypted at rest.
3. Enter the Endpoint URL.
4. Optionally fill in API Version, Model, Deployment, and Custom Header.
5. Click Save.

Here's an overview of the LLM configuration fields:

Field	Required	Description
provider	Yes	The LLM provider. Currently only azure_openai is supported.
api_key	Yes	The API key for the provider. Encrypted at rest; only the last 4 characters are shown after saving.
endpoint	Yes	The URL of the LLM endpoint.
api_version	No	The API version defined by the provider.
model	No	The model name.
deployment	No	The deployment name, which may differ from the model name.
custom_header	No	An optional header name for including the API key in requests to the provider.

The LLM section can be saved independently of the Embedder section.

info

If the LLM is not configured, Witty pods start normally. Errors will only occur at invocation time.

Configure LLM via API

For programmatic or advanced configuration management, the following APIs are available:

• GET /witty/v1/llm/config: retrieve the LLM configuration;
• POST /witty/v1/llm/config: create/edit a LLM configuration. The body is a JSON in the LLM structure seen before;
• POST /witty/v1/llm/chat: chat with LLM. The body is a JSON with this format

{
    "query": "Some text"
}

Here's an example of a LLM configuration:

{
    "provider": "azure_openai",
    "api_key": "xxx",
    "endpoint": "https://xxx.cognitiveservices.azure.com/",
    "api_version": "2025-01-01-preview",
    "model": "gpt-4.1",
    "deployment": "gpt-4.1",
    "custom_header": "X-API-Key"
}

Supported providers

Currently the available providers for LLM configuration are:

LLM Provider	Description
azure_openai	Azure OpenAI Service

Note: Azure OpenAI can be accessed through Azure Foundry and Azure API Management (APIM). In the first case, the endpoint field should be the Azure Foundry endpoint, while in the second case it should be the Azure API Management endpoint. If you are using Azure API Management, you can also include the custom_header field with the name of the header where the APIM subscription key is expected (e.g. X-API-Key).

Supported models

Currently Witty microservice has been tested against the following models/providers:

LLM Provider	Model
azure_openai	gpt-5.2-chat (preferred)
azure_openai	gpt-4.1
azure_openai	gpt-5
azure_openai	gpt-4.5-preview
azure_openai	gpt-4o
azure_openai	o1

Embedder Configuration

Witty needs a valid embedder model. The recommended way to configure the embedder model is through Administration > Configuration > Witty. In the Embedder section:

1. Select azure_openai from the Provider dropdown (the only currently supported option).
2. Enter your API Key. After saving, only the last 4 characters will be visible — the key is encrypted at rest.
3. Enter the Endpoint URL.
4. Optionally fill in API Version, Model, Deployment, and Custom Header.
5. Click Save.

Here's an overview of the Embedder configuration fields:

Field	Required	Description
provider	Yes	The embedder provider. Currently only azure_openai is supported.
api_key	Yes	The API key for the provider. Encrypted at rest; only the last 4 characters are shown after saving.
endpoint	Yes	The URL of the embedder endpoint.
api_version	No	The API version defined by the provider.
model	No	The embedding model name.
deployment	No	The deployment name, which may differ from the model name.
custom_header	No	An optional header name for including the API key in requests to the provider.

The Embedder section can be saved independently of the LLM section.

info

If the Embedder is not configured, Witty pods start normally. Errors will only occur when embedder functionality is invoked (e.g., Marketplace embedding search).

Configure Embedder via API

For programmatic or advanced configuration management, the following APIs are available:

• GET /witty/v1/embedder/config: retrieve the embedder configuration;
• POST /witty/v1/embedder/config: create/edit a embedder configuration. The body is a JSON in the embedder structure seen before.

Here's an example of a embedder configuration:

{
    "provider": "azure_openai",
    "api_key": "xxx",
    "endpoint": "https://xxx.cognitiveservices.azure.com/",
    "api_version": "2025-01-01-preview",
    "model": "text-embedding-3-large",
    "deployment": "text-embedding-3-large-witty",
    "custom_header": "X-API-Key"
}

Supported providers

Currently the available providers for Embedder configuration are:

Embedder Provider	Description
azure_openai	Azure OpenAI Service

Note: Azure OpenAI can be accessed through Azure Foundry and Azure API Management (APIM). In the first case, the endpoint field should be the Azure Foundry endpoint, while in the second case it should be the Azure API Management endpoint. If you are using Azure API Management, you can also include the custom_header field with the name of the header where the APIM subscription key is expected (e.g. X-API-Key).

Supported models

Currently Witty microservice has been tested against the following models/providers:

Embedder Provider	Model
azure_openai	text-embedding-3-large
azure_openai	text-embedding-3-small