As developers, we're constantly looking for tools that not only solve problems but do so elegantly and efficiently. If you're working with dotCMS, you already know about its robust content management capabilities – but have you tapped into the power of dotAI yet? This AI service isn't just another checkbox feature; it's a comprehensive toolkit that can transform how you build intelligent, context-aware applications.
In this guide, we'll dive deep into the dotAI REST API ecosystem, exploring practical implementations that go beyond the basic documentation. Let's turn those dry API references into working code that solves real problems.
Understanding the dotAI API Landscape
Before we start building, let's map the territory. The dotAI API is organized into four primary domains:
Generative APIs - For creating text and image content
Search APIs - For intelligent, context-aware content discovery
Embeddings APIs - For building and managing vector representations of your content
Completions APIs - For leveraging LLM capabilities with your existing content
All these endpoints live under the /api/v1/ai path, making them easy to discover and integrate.
Please check and perform the proper configuration of dotCMS before proceeding. Instructions can be found here https://dev.dotcms.com/docs/dotai
Text Generation: Beyond Simple Prompts
Let's start with something every developer loves: generating content programmatically. The text generation API is deceptively simple but incredibly powerful.
For quick text generation, a GET request with a prompt parameter works perfectly:
curl -X 'GET' \
'http://your-dotcms-instance/api/v1/ai/text/generate?prompt=Explain%20microservices%20architecture' \
-H 'accept: application/json'But where things get interesting is with the POST endpoint, which gives you granular control over the generation process:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/text/generate' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "Write a product description for a cloud-native CMS",
"temperature": 0.7,
"model": "gpt-4o-mini",
"responseLengthTokens": 256
}'This flexibility lets you fine-tune the AI's creativity level with temperature settings or switch between models for different types of content. For product descriptions, I've found that a temperature of 0.7 strikes a good balance between creativity and coherence, while technical documentation might benefit from a lower setting around 0.3 for more predictable outputs.
Image Generation: Content That Catches the Eye
Need visuals to accompany your content? The image generation API follows the same pattern as text generation:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/image/generate' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "A 3D rendering of a modern content management system dashboard",
"numberOfImages": 1,
"size": "1024x1024"
}'A practical tip: Be specific with your image prompts. Rather than "a CMS dashboard," try "A sleek, modern CMS dashboard with analytics widgets and content blocks, using a blue and white color scheme." The more details you provide, the closer the result will be to your vision.
Semantic Search: Finding Content That Matters
The dotAI search capabilities go far beyond keyword matching. Using vector embeddings, you can find content based on semantic meaning rather than exact word matches:
curl -X 'GET' \
'http://your-dotcms-instance/api/v1/ai/search?query=increasing%20website%20performance&indexName=blogIndex' \
-H 'accept: application/json'This returns not just exact matches for "website performance" but content that conceptually relates to the topic, even if it uses different terminology like "optimizing page load times" or "improving site responsiveness."
One of my favorite features is the related content search, which is perfect for building "You might also like" sections:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/search/related' \
-H 'Content-Type: application/json' \
-d '{
"identifier": "3d6fa2a4-2b48-4421-a2f5-b6518a7c0830",
"fieldVar": "blogContent",
"indexName": "blogIndex"
}'Working with Embeddings: The Engine Behind Semantic Search
For developers looking to customize how content is indexed and searched, the embeddings API offers granular control:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/embeddings' \
-H 'Content-Type: application/json' \
-d '{
"query": "+contentType:blogPost +live:true",
"fields": "headline,body",
"indexName": "blogIndex",
"model": "text-embedding-ada-002"
}'This creates vector embeddings for all matching content, which powers the semantic search capability. You can create multiple indexes for different content types, allowing for more focused and relevant search results.
A real-world implementation I've found useful is creating specialized indexes for different content domains. For example, maintain separate indexes for technical documentation, marketing content, and support articles to ensure that search results stay contextually relevant to the user's current section of your site.
Completions API: Contextual Content Generation
The completions API is where dotAI really shines for content-aware operations. It combines the power of large language models with your existing content:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/completions' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "What are the key benefits of headless CMS architecture?",
"indexName": "techDocIndex",
"threshold": 0.2,
"searchLimit": 5
}'This doesn't just generate a generic response – it searches your indexed content for relevant information about headless CMS benefits and uses that to inform the AI-generated response. The result is content that feels custom-tailored to your specific knowledge base.
For streaming responses, which can improve perceived performance in user interfaces, add the "stream": true parameter:
curl -X 'POST' \
'http://your-dotcms-instance/api/v1/ai/completions' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "Explain our content workflow process",
"indexName": "internalDocs",
"stream": true
}'Building a Real-World AI-Powered Feature
Let's put these APIs together to build something practical: an automated content enrichment system that:
Takes a draft blog post
Generates relevant images based on the content
Finds related articles from your existing content
Suggests improvements to the text
Here's what the implementation might look like in JavaScript:
async function enrichContent(draftContent, contentType = 'blogPost') {
// 1. Extract key topics from the draft
const topicsResponse = await fetch('/api/v1/ai/text/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
prompt: Extract 3-5 key topics from this content as a JSON array: "${draftContent.substring(0, 1000)}...",
temperature: 0.2
})
});
const topicsResult = await topicsResponse.json();
const topics = JSON.parse(topicsResult.choices[0].message.content);
// 2. Generate a relevant image based on the content
const imagePrompt = Create an engaging featured image for an article about ${topics.join(', ')};
const imageResponse = await fetch('/api/v1/ai/image/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
prompt: imagePrompt,
size: '1024x1024'
})
});
const imageResult = await imageResponse.json();
// 3. Find related content from your CMS
const relatedContentResponse = await fetch('/api/v1/ai/search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
prompt: topics.join(' '),
indexName: contentType + 'Index',
threshold: 0.25,
searchLimit: 3
})
});
const relatedContent = await relatedContentResponse.json();
// 4. Get content improvement suggestions
const improvementResponse = await fetch('/api/v1/ai/completions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
prompt: Suggest 3 ways to improve this content for SEO and readability: "${draftContent.substring(0, 1500)}...",
indexName: 'seoGuidelines'
})
});
const improvements = await improvementResponse.json();
return {
enrichedContent: draftContent,
suggestedImage: imageResult.url,
relatedArticles: relatedContent.dotCMSResults.map(r => ({
title: r.title,
url: r.url,
relevanceScore: r.matches[0].distance
})),
improvementSuggestions: improvements.openAiResponse.choices[0].message.content
};
}This function could be integrated into your editorial workflow, providing automatic enrichment suggestions as soon as a draft is saved.
Performance Considerations
When working with AI APIs, response times can vary. For user-facing implementations, consider these optimization strategies:
Use streaming responses where appropriate to improve perceived performance
Implement caching for common queries, especially for related content searches
Pre-generate embeddings during content publishing rather than on-demand
Set appropriate thresholds for search to balance relevance and speed
The dotAI embeddings API includes configuration options for cache size and TTL (Time To Live), which can be tuned based on your content volume and update frequency:
curl -X 'GET' \
'http://your-dotcms-instance/api/v1/ai/completions/config' \
-H 'accept: application/json'This returns the current configuration, including cache settings like:
{
"com.dotcms.ai.embeddings.cache.size": "1000",
"com.dotcms.ai.embeddings.cache.ttl.seconds": "600"
}Security and Authentication
Like all dotCMS APIs, the dotAI endpoints respect user permissions and require proper authentication. In production environments, always use secure connections and appropriate authentication methods as described in the dotCMS REST API Authentication documentation.
Conclusion: Building Smarter Applications with dotAI
The dotAI APIs provide a powerful toolkit for adding intelligent features to your dotCMS implementations. From content generation to semantic search, these capabilities can transform static content management into dynamic, context-aware experiences.
The real power comes from combining these APIs creatively. Consider use cases like:
Automated content tagging and categorization
Intelligent search that understands user intent
Dynamic FAQ systems that leverage your existing knowledge base
Content recommendations that truly understand relevance
Automated content summarization for different audience segments
As you experiment with these APIs, you'll likely discover even more creative applications. The dotAI service isn't just about automating content creation – it's about making your entire content ecosystem smarter and more responsive to user needs.
What intelligent features are you planning to build with dotAI? Let us know in the comments below, or share your implementations with the dotCMS developer community.