> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/concepts/settings.md).

# Settings

Global AI settings configure default profiles and system-wide behavior.

AI Settings provide a central place to configure system-wide defaults for Umbraco.AI. These settings are stored in the database and managed through the backoffice or programmatically.

## What Settings Store

| Property                          | Description                                                                                                                       |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Id`                              | Fixed identifier (always the same GUID)                                                                                           |
| `DefaultChatProfileId`            | The profile used when no profile is specified for chat operations                                                                 |
| `DefaultEmbeddingProfileId`       | The profile used when no profile is specified for embedding operations                                                            |
| `DefaultSpeechToTextProfileId`    | The profile used when no profile is specified for speech-to-text operations                                                       |
| `DefaultImageGenerationProfileId` | The profile used when no profile is specified for image generation (experimental)                                                 |
| `ClassifierChatProfileId`         | Optional profile for internal classification tasks (e.g., agent routing). Falls back to default chat profile                      |
| `DefaultDecisionProfileId`        | The profile used when no profile is specified for decisions (experimental). Also used by Auto agent mode when Decision is enabled |
| `DisclosureNoticeMode`            | How the backoffice shows the notice that tells users a response is AI-generated: `Always` (default), `Dismissible`, or `Off`      |

{% hint style="info" %}
Settings are a singleton entity - there is only one settings record for the entire application.
{% endhint %}

## Configuring Default Profiles

The recommended way to configure default profiles is through the backoffice. See [Managing Settings](/ai-in-umbraco/backoffice/managing-settings.md) for step-by-step instructions.

## Using Settings in Code

### Getting Current Settings

{% code title="Example.cs" %}

```csharp
public class SettingsExample
{
    private readonly IAISettingsService _settingsService;

    public SettingsExample(IAISettingsService settingsService)
    {
        _settingsService = settingsService;
    }

    public async Task<AISettings> GetCurrentSettings()
    {
        return await _settingsService.GetSettingsAsync();
    }
}
```

{% endcode %}

### Updating Settings

{% code title="Example.cs" %}

```csharp
public async Task UpdateDefaultProfile(Guid chatProfileId)
{
    var settings = await _settingsService.GetSettingsAsync();
    settings.DefaultChatProfileId = chatProfileId;
    await _settingsService.SaveSettingsAsync(settings);
}
```

{% endcode %}

## How Default Profiles Work

When you call an AI service without specifying a profile:

1. The service checks for a default profile in AI Settings (database).
2. If not found, an exception is thrown.

{% code title="Example.cs" %}

```csharp
// Uses the default chat profile from Settings
var response = await _chatService.GetChatResponseAsync(
    chat => chat.WithAlias("content-chat"),
    messages);

// Explicitly specifies a profile (overrides default)
var response = await _chatService.GetChatResponseAsync(
    chat => chat.WithAlias("content-chat").WithProfile(profileId),
    messages);
```

{% endcode %}

## Classifier Chat Profile

The classifier chat profile is an optional setting that allows you to designate a cheaper or faster model for internal classification tasks. Currently, this is used by the "Auto" agent mode in both Contextual Copilot and Copilot Workspace. It classifies user prompts and routes them to the best available agent.

### Fallback Chain

When the classifier profile is requested:

1. **Database settings** — `ClassifierChatProfileId` (configured in backoffice)
2. **Configuration file** — `ClassifierChatProfileAlias` in `appsettings.json`
3. **Default chat profile** — Falls back to the standard default chat profile

The fallback chain means you only need to configure the classifier profile if you want to use a different (typically cheaper) model for classification. If not set, the default chat profile is used automatically.

### Decision-Based Routing

When the experimental [Decision](/ai-in-umbraco/using-the-api/decision.md) capability is enabled and a default Decision profile is set, Auto mode asks the Decision profile to pick the agent first. The classifier chat profile is only used when that is not possible. See [Auto Mode](/ai-in-umbraco/add-ons/agent-copilot/copilot.md#auto-mode-and-agent-routing).

## AI Disclosure Notice

`DisclosureNoticeMode` controls the "Responses are AI-generated and may be inaccurate." notice shown in the Contextual Copilot and Copilot Workspace chat, and in the prompt preview. It uses the `AIDisclosureNoticeMode` enum:

| Value         | Behavior                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `Always`      | The notice is always shown (default). Missing or unknown values also fall back to this.         |
| `Dismissible` | The notice can be dismissed. Each location (chat, prompt) is dismissed separately, per browser. |
| `Off`         | The notice is never shown.                                                                      |

Unlike the profile settings, this setting has no `appsettings.json` fallback. When deploying with [Umbraco Deploy](/ai-in-umbraco/add-ons/deploy.md), the mode travels with the settings. Artifacts created before this setting existed keep the target environment's value.

See [Managing Settings](/ai-in-umbraco/backoffice/managing-settings.md#ai-disclosure-notice) for how each option behaves in the backoffice.

## Configuration File Fallback

For advanced scenarios like Continuous Integration/Continuous Deployment (CI/CD) pipelines or infrastructure-as-code, you can configure defaults via `appsettings.json`:

{% code title="appsettings.json" %}

```json
{
    "Umbraco": {
        "AI": {
            "DefaultChatProfileAlias": "content-writer",
            "DefaultEmbeddingProfileAlias": "embeddings",
            "DefaultSpeechToTextProfileAlias": "transcription",
            "DefaultImageGenerationProfileAlias": "hero-images",
            "DefaultDecisionProfileAlias": "moderation",
            "ClassifierChatProfileAlias": "fast-classifier"
        }
    }
}
```

{% endcode %}

{% hint style="warning" %}
Database settings (configured via backoffice) take precedence over configuration file settings. Use configuration files only when you need environment-specific defaults that can't be managed through the backoffice.
{% endhint %}

## Managing Settings

### Via Backoffice

You can configure settings through the backoffice. See [Managing Settings](/ai-in-umbraco/backoffice/managing-settings.md) for step-by-step instructions.

### Via Management API

{% code title="Management API endpoints" %}

```http
GET /umbraco/ai/management/api/v1/settings
PUT /umbraco/ai/management/api/v1/settings
GET /umbraco/ai/management/api/v1/settings/disclosure
```

{% endcode %}

See [Settings API](/ai-in-umbraco/management-api/settings.md) for details.

## Related

* [Profiles](/ai-in-umbraco/concepts/profiles.md) - The profiles that can be set as defaults
* [Managing Settings](/ai-in-umbraco/backoffice/managing-settings.md) - Backoffice guide


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/concepts/settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.