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 — OpenAI, Azure OpenAI, and Google Vertex AI (Gemini) — configured via the providerConfig JSON in the App settings. 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, or
• Deploy the dotAI plugin (only for legacy versions prior to dotCMS 24.04.05 that meet the requirements)

Requirements#

---

This feature requires the following:

1. Credentials for your chosen AI provider (see App Configuration for provider-specific requirements);
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. Each section declares its own provider independently, so you can mix providers freely — for example, Vertex AI for chat and OpenAI for embeddings and images.

Common Fields#

The following fields are available in the chat, embeddings, and image sections across all providers. Provider-specific fields are documented in the sections below.

Provider-Specific Fields#

Azure OpenAI (azure_openai)#

Prerequisites: An active Azure subscription with Azure OpenAI access enabled; an Azure OpenAI resource created in Azure AI Studio with one or more model deployments; the resource's API key and endpoint URL (found in Azure AI Studio → Your Resource → Keys and Endpoint).

*deploymentName or model is required. If your deployment name matches the model name exactly, model alone is sufficient; otherwise use deploymentName.

Note on reasoning models. Models in the o1, o3, and o4-mini families use max_completion_tokens instead of max_tokens at the API level. dotAI detects this automatically — set maxTokens as usual.

Note on API keys and multi-resource deployments. Azure scopes API keys to the resource, not to individual deployments. If your chat and embeddings deployments live in the same resource, both sections share the same apiKey and endpoint. If deployments span multiple resources, use the appropriate key and endpoint per section.

Google Vertex AI (vertex_ai)#

Prerequisites: A Google Cloud project with the Vertex AI API enabled; a service account with the Vertex AI User role or equivalent; either a downloaded service account key file (JSON) or workload identity configured (for GKE / Cloud Run).

Supported sections: chat only. Vertex AI Gemini does not support embeddings or image generation through this integration — those sections must use a different provider.

model defaults to gemini-1.5-flash if omitted; recommended values include gemini-2.0-flash and gemini-1.5-pro. See the Vertex AI model garden for availability by region. us-central1 has the broadest coverage.

Authentication. Two options are supported:

• Service account key file (recommended for on-premise / non-GCP deployments): paste the full content of your key file into credentialsJson. The value must be a single escaped JSON string — not an inline JSON object. To produce the correct format: cat my-key.json | python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))"
• Application Default Credentials (recommended for GKE / Cloud Run): omit credentialsJson. dotAI uses ADC automatically, respecting workload identity and environment-level credentials.

Provider Capability Summary#

Settings#

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 — OpenAI (standard)#

Sufficient for most OpenAI 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"
  }
}

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

Azure OpenAI — chat and embeddings#

A minimal Azure configuration. Image generation here falls back to OpenAI; for a full Azure image setup see the example below.

{
  "chat": {
    "provider": "azure_openai",
    "apiKey": "YOUR_AZURE_API_KEY",
    "endpoint": "https://my-resource.openai.azure.com/",
    "deploymentName": "my-gpt4o-deployment",
    "apiVersion": "2024-02-01",
    "maxTokens": 16384
  },
  "embeddings": {
    "provider": "azure_openai",
    "apiKey": "YOUR_AZURE_API_KEY",
    "endpoint": "https://my-resource.openai.azure.com/",
    "deploymentName": "my-embeddings-deployment",
    "apiVersion": "2024-02-01"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-image-1"
  }
}

If your deployment name matches the model name exactly, you can omit deploymentName and use model alone:

{
  "chat": {
    "provider": "azure_openai",
    "apiKey": "YOUR_AZURE_API_KEY",
    "endpoint": "https://my-resource.openai.azure.com/",
    "model": "gpt-5.4",
    "apiVersion": "2024-02-01",
    "maxTokens": 16384
  }
}

Azure OpenAI — full configuration with image generation#

Azure supports two endpoint types for image generation, selected automatically based on the endpoint URL. In early 2026, Microsoft retired DALL-E 3 image deployments on Azure OpenAI in favour of the gpt-image series.

• *.openai.azure.com (Classic Azure OpenAI): requires deploymentName and apiVersion; supports gpt-image-1.
• *.services.ai.azure.com (Azure AI Foundry): uses a plain OpenAI-style client; do not set apiVersion (it produces a warning if present); supports gpt-image-2.

Full configuration using the Foundry endpoint for images:

{
  "chat": {
    "provider": "azure_openai",
    "apiKey": "YOUR_AZURE_API_KEY",
    "endpoint": "https://my-resource.openai.azure.com/",
    "deploymentName": "my-gpt4o-deployment",
    "apiVersion": "2024-02-01",
    "maxTokens": 16384
  },
  "embeddings": {
    "provider": "azure_openai",
    "apiKey": "YOUR_AZURE_API_KEY",
    "endpoint": "https://my-resource.openai.azure.com/",
    "deploymentName": "my-embeddings-deployment",
    "apiVersion": "2024-02-01"
  },
  "image": {
    "provider": "azure_openai",
    "apiKey": "YOUR_FOUNDRY_API_KEY",
    "endpoint": "https://my-resource.services.ai.azure.com/openai/v1/",
    "model": "gpt-image-2",
    "size": "1024x1024"
  }
}

Google Vertex AI (Gemini) — chat only#

Vertex AI supports chat only; embeddings and images must use a separate provider.

{
  "chat": {
    "provider": "vertex_ai",
    "projectId": "my-gcp-project",
    "location": "us-central1",
    "model": "gemini-2.0-flash",
    "credentialsJson": "{ ... service account JSON ... }"
  },
  "embeddings": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-ada-002"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "gpt-image-1"
  }
}

To use Application Default Credentials instead of a key file, omit credentialsJson:

{
  "chat": {
    "provider": "vertex_ai",
    "projectId": "my-gcp-project",
    "location": "us-central1",
    "model": "gemini-2.0-flash",
    "maxTokens": 8192
  }
}

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. Credentials are masked as ***** in the response.

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: