dotAI integrates powerful AI tools into your dotCMS instance, allowing new horizons of automation — content and image generation, semantic searches, and more. Through workflows, dotAI is capable of performing batch operations — such as adding images to any content that's missing an image, or automatically generating SEO metadata to large swaths of content, adding content tags, and numerous other tasks.

dotAI supports multiple AI service providers, configured via the providerConfig JSON in the App settings. OpenAI is a commonly used provider. Additionally, the dotAI features will soon be available by default; at this moment, it requires one of two activation methods:

• Enable the dotAI tool through the admin panel (dotCMS 24.04.05 or later), or
• Deploy the dotAI plugin (earlier versions that meet the requirements)

Requirements#

---

This feature requires the following:

1. An API key for your chosen AI provider (e.g., OpenAI), obtained separately;
2. Postgres 18 with the pgvector extension installed.
   • If you're on dotCMS Cloud, we'll handle it!
   • For self-hosted customers, see below.

Self-Hosted#

For embeddings to function, a vector extension must be added to the Postgres database. The dotAI plugin will add this extension automatically, but this process requires dotCMS's database user has superuser privileges, ensuring extensions can be installed.

If the database user does not have sufficient rights, it may be necessary for IT or administrators to manually add the extension. The simplest implementation is via the pgvector/pgvector Docker tag, easily accessible via the command docker pull pgvector/pgvector. The image can be applied to a docker-compose.yml by adding it to the database section:

 db:
    image: pgvector/pgvector

Note also that these privileges are only required for the extension's installation, and not for its subsequent use.

App Configuration#

---

dotAI is configured via a single Provider Config (JSON) field in Settings > Apps > dotAI. All configuration — provider credentials, model selection, prompts, and behavioral settings — is expressed as a JSON object in this field.

The JSON has up to four top-level properties: chat, embeddings, image, and settings.

The chat, embeddings, and image properties accept the following fields:

The settings property carries behavioral and prompt configuration:

Only include settings that differ from the defaults shown above — omitted keys fall back to their default values.

Each site can have its own providerConfig, or inherit the configuration from SYSTEM_HOST. To configure a specific site, select it from the site picker in Settings > Apps > dotAI before saving.

Once installed and configured, the dotCMS surfaces a variety of utilities. The section below provides a brief overview of each, and a link to further documentation.

Configuration Examples#

Minimal (standard OpenAI, default behavior)#

Sufficient for most deployments. Omit any section you don't use.

{
  "chat": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-4o",
    "maxTokens": 16384,
    "maxRetries": 3
  },
  "embeddings": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-ada-002"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "dall-e-3"
  }
}

With Custom Settings#

Use the settings block only for values that differ from the defaults.

{
  "chat": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-4o,gpt-4o-mini",
    "maxTokens": 16384,
    "temperature": 0.7,
    "maxRetries": 3,
    "endpoint": "https://your-proxy.example.com/v1/chat/completions"
  },
  "embeddings": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-ada-002"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "dall-e-3"
  },
  "settings": {
    "rolePrompt": "You are a helpful assistant for Acme Corp.",
    "textPrompt": "Be concise and professional.",
    "imagePrompt": "Use a clean, corporate visual style.",
    "imageSize": "1792x1024",
    "listenerIndexer": {
      "default": "blog,news,webPageContent"
    },
    "embeddingsSplitAtTokens": 256,
    "embeddingsSearchThreshold": 0.3,
    "debugLogging": false
  }
}

This configuration is more advanced, including model fallbacks and a custom endpoint.

Per-Site Config#

To configure a specific site, go to Settings > Apps > dotAI, select the target site from the site picker, and save a separate providerConfig JSON.

To verify which host's config is being applied, check the configHost field in the GET response:

GET /api/v1/ai/completions/config?siteId=your-site-id

{
  "providerConfig": "{ ... }",
  "configHost": "SYSTEM_HOST"
}

If configHost returns the target site's hostname, the per-site config is active.

Legacy Configuration#

Before the implementation of the provider configuration specified above, the dotAI App Configuration followed a different, multiple-field pattern. A full list of the legacy fields follows:

Using dotAI#

---

The dotAI feature includes several components, detailed separately: