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, Google Vertex AI (Gemini), and Amazon Bedrock — 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 (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.

Amazon Bedrock (bedrock)#

Prerequisites: An active AWS account with Amazon Bedrock access; model access explicitly enabled for each model you intend to use (AWS Console → Amazon Bedrock → Model access — IAM permissions alone are not sufficient); an IAM identity with bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream permissions on the target models.

Supported sections: chat and embeddings. Image generation is not supported — configuring provider: "bedrock" for the image section throws an UnsupportedOperationException. Use a different provider for images.

Authentication. Two options are supported:

• Static credentials (IAM user): provide accessKeyId and secretAccessKey together. Both must be present — supplying only one throws an IllegalArgumentException at startup.
• Default credential chain (recommended for EC2, EKS, ECS): omit both fields. dotAI uses the AWS SDK's DefaultCredentialsProvider, which resolves credentials in order: environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) → system properties → AWS profile files (~/.aws/credentials) → EKS IRSA web identity / container role metadata.

Model ID forms. Bedrock uses two distinct ID formats depending on the model's throughput type:

• Inference-profile-prefixed IDs — required for models that only support cross-region inference profiles (no on-demand throughput). Must include a region prefix: us., eu., or apac.. Using the bare ID for these models returns a ValidationException.
• Bare on-demand IDs — for models with on-demand throughput. No prefix needed.

Model availability varies by region — check the Bedrock model catalog for your account. The IDs above have been live-tested against the dotCMS R&D Bedrock account.

Embedding model families. Two families are supported, with different routing and constraints:

• Amazon Titan (amazon.titan-*): routed to BedrockTitanEmbeddingModel. Titan V1 always outputs 1536 dimensions, matching the default dot_embeddings pgvector schema (vector(1536)) with no schema changes required. Titan V2 supports configurable dimensions (256, 512, or 1024) via the dimensions field but requires a schema migration unless the instance was configured for a lower dimension from the start.
• Cohere (cohere.*): routed to BedrockCohereEmbeddingModel. Use embeddingInputType to specify the input hint appropriate for your use case.

timeout and maxRetries are not applied to either embedding family — the underlying Bedrock client for embeddings does not expose SDK override configuration.

Additional considerations:

• timeout is a per-attempt timeout mapping to the AWS SDK's apiCallAttemptTimeout. Each retry gets the full budget — with maxRetries: 2 and timeout: 30, worst-case total wait is 90 seconds.
• DeepSeek R1 requires the us. inference-profile prefix. The bare ID deepseek.r1-v1:0 is rejected with a ValidationException.
• gpt-oss models require langchain4j-bedrock 1.16.0 or later. Earlier versions unconditionally include stopSequences in Converse requests, which the gpt-oss family rejects with a ValidationException. This affects both chat and streaming; DeepSeek R1 and Titan embeddings work correctly on earlier versions.

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

Amazon Bedrock — chat and embeddings (Titan V1, static credentials)#

Titan V1 is recommended when no pgvector schema migration is possible, as its 1536-dimension output matches the default dot_embeddings schema directly.

{
  "chat": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "us.deepseek.r1-v1:0",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "amazon.titan-embed-text-v1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Amazon Bedrock — chat and embeddings (Titan V2)#

Requires a dot_embeddings schema configured for 1024 dimensions or fewer.

{
  "chat": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "us.deepseek.r1-v1:0",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "amazon.titan-embed-text-v2:0",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "dimensions": 1024
  }
}

Amazon Bedrock — default credential chain (EC2 / EKS / ECS)#

Omit both credential fields when the instance or pod has an attached IAM role.

{
  "chat": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "us.deepseek.r1-v1:0",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "amazon.titan-embed-text-v1"
  }
}

Amazon Bedrock chat with OpenAI embeddings and images#

{
  "chat": {
    "provider": "bedrock",
    "region": "us-east-1",
    "model": "us.deepseek.r1-v1:0",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-ada-002"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "dall-e-3"
  }
}

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: