dotAI

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), Amazon Bedrock, Google AI (Gemini API), Anthropic (Claude), and OpenRouter — configured in Settings > Apps > dotAI. On dotCMS 24.04.05 and later, the feature is included by default. On earlier versions, it must be enabled manually or activated via the dotAI plugin.

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 at Settings > Apps > dotAI via the dotAI Configuration screen. It provides a structured form for each AI capability — Chat, Embeddings, and Image Generation — plus a Settings section for prompts and behavioral defaults. Each capability can be enabled or disabled independently, and each can use a different provider, so you can mix providers freely.

Configuration Interface#

The configuration screen presents four cards stacked vertically. Click Save Configuration (pinned to the bottom right) to apply changes. To configure a specific site rather than the default, select it from the site picker in the top-right corner before saving.

Capability Cards#

The Chat, Embeddings, and Image Generation cards each follow the same layout:

• Enable/disable toggle (top right of the card) — enables or disables that capability entirely, independently of the others.

• Provider tile grid — one tile per supported provider, showing which capabilities that provider offers. Providers that don't support the card's capability are greyed out and labeled "No X support." Click a tile to select it; the required and optional fields below update to match that provider.

• Required fields — shown above the Advanced panel, marked with a red asterisk. Which fields appear depends on the selected provider (see table below). Api key and Secret access key values are masked after saving and must be re-entered to change.

• Advanced N optional field(s) — a collapsible panel revealing additional provider-specific fields. The count in the label reflects the number of optional fields for the selected provider. The Embeddings and Image Generation cards omit Max tokens from this panel; all other advanced fields are the same as for Chat.

• Additional properties — at the bottom of the Advanced panel, a + Add Property button lets you add freeform key-value pairs for provider-specific fields not yet modeled in the form.

• Test Connection — sends a live request to the configured provider and reports success or failure, allowing you to verify credentials before saving. On success, a green checkmark and "Connection successful." appear inline next to the button. On failure, a red error icon and the raw JSON error response from the provider appear below the button.

  

  

Required fields by provider:

Advanced fields by provider (Chat card):

For the Embeddings and Image Generation cards, the advanced fields are the same as above except Max tokens is not shown.

Settings Card#

The Settings card at the bottom of the page configures behavior and prompts that apply across all capabilities.

The following fields are always visible:

Expanding Advanced 12 settings reveals the embeddings and runtime configuration:

See Settings for the JSON field names, defaults, and full descriptions of each setting.

The Settings card also includes an Additional properties section. Unlike the capability cards, where Additional properties accepts arbitrary provider-specific fields, the Settings card's Additional properties section is for recognized settings keys that don't yet have dedicated form fields. The current set is:

See Settings for defaults and full descriptions.

JSON Reference#

The configuration screen saves all settings as a providerConfig JSON object. The reference below documents every field in that object, which can also be supplied directly via the API for automation or headless configuration workflows.

The JSON has up to four top-level properties: chat, embeddings, image, and settings. Each section declares its own provider independently.

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#

Set provider to "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#

Set provider to "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#

Set provider to "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.

Google AI#

Set provider to "google_ai".

Prerequisites: A Google account with access to Google AI Studio; an API key generated at AI Studio → Get API key; a billing-enabled Google Cloud project linked to the API key. The free-tier quota is very limited — billing must be active for production use.

Supported sections: chat, embeddings, and image.

Chat model IDs:

Embedding model IDs:

Image model IDs:

maxRetries and timeout are not applied for streaming chat and are silently ignored in that mode.

Anthropic#

Set provider to "anthropic".

Prerequisites: An Anthropic account with an active plan; an API key (sk-ant-...) generated at Anthropic Console → API Keys.

Supported sections: chat only. Anthropic provides no embeddings or image generation API — both sections must use a different provider.

Note on direct vs. Bedrock access. This provider calls the Anthropic API directly with an sk-ant-... key. To access Claude models through AWS infrastructure instead, use provider: "bedrock" with the appropriate Bedrock model ID (e.g. anthropic.claude-3-5-sonnet-20241022-v2:0).

maxRetries is not applied for streaming chat and is silently ignored in that mode.

OpenRouter#

Set provider to "openrouter".

Prerequisites: An OpenRouter account with credits or an active plan; an API key (sk-or-...) generated at OpenRouter → Keys.

Supported sections: chat and embeddings. Image generation is not supported — the image section must use a different provider.

Chat model IDs — OpenRouter routes to hundreds of models through a single API key. Common examples:

Full model list at openrouter.ai/models.

Embedding model IDs — OpenRouter proxies approximately 10 embedding models via an OpenAI-compatible /api/v1/embeddings endpoint. Common examples:

Full embedding model list at openrouter.ai/collections/embedding-models.

Not all models are available on all plans — check your plan's access before using in production.

maxRetries is not applied for streaming chat and is silently ignored in that mode.

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 configuration, or inherit from SYSTEM_HOST. To configure a specific site, select it from the site picker in Settings > Apps > dotAI before saving.

Configuration Examples#

OpenAI: Minimal#

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: Custom#

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: Minimal#

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: Full#

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

Vertex AI#

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

Bedrock: Titan V1#

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

Bedrock: Titan V2#

Uses Titan Embed Text V2 for embeddings. 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
  }
}

Bedrock: IAM Role#

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

Bedrock: Mixed#

Bedrock for chat, OpenAI for 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"
  }
}

Google AI: Full#

Use dimensions: 1536 with gemini-embedding-001 to match the default pgvector schema without a migration.

{
  "chat": {
    "provider": "google_ai",
    "model": "gemini-2.0-flash",
    "apiKey": "AIza...",
    "maxTokens": 8192,
    "temperature": 0.7
  },
  "embeddings": {
    "provider": "google_ai",
    "model": "gemini-embedding-001",
    "apiKey": "AIza...",
    "dimensions": 1536
  },
  "image": {
    "provider": "google_ai",
    "model": "gemini-2.5-flash-image",
    "apiKey": "AIza..."
  }
}

Anthropic#

Anthropic supports chat only; embeddings and images must use a different provider.

{
  "chat": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-...",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "text-embedding-ada-002"
  },
  "image": {
    "provider": "openai",
    "apiKey": "sk-...",
    "model": "dall-e-3"
  }
}

OpenRouter#

OpenRouter uses namespaced model IDs (provider/model-name) for both chat and embeddings. Image generation must use a different provider.

{
  "chat": {
    "provider": "openrouter",
    "model": "openai/gpt-4o",
    "apiKey": "sk-or-...",
    "maxTokens": 8192
  },
  "embeddings": {
    "provider": "openrouter",
    "model": "openai/text-embedding-3-small",
    "apiKey": "sk-or-..."
  },
  "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 configuration.

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 current configuration interface, 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: